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Preface 


Apple® File Exchange is an application for moving files between the Apple 
Macintosh family of computers, the Apple II family of computers, and other 
computers. This manual describes how to write file conversion routines, known as 
translators, that are used by Apple File Exchange. 
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Audience 


This manual is written both for professional programmers and for enthusiasts. It is 
distributed by the Apple Programmer's and Developer's Association (APDA). The 
manual assumes that readers are experienced Macintosh programmers and that they 
are familiar with the Macintosh User Interface Toolbox and Operating System routines 
described in Inside Macintosh. It also assumes that readers have used Apple File 
Exchange and are familiar with the program's features. Readers who are not already 
experienced Apple File Exchange users should read the chapters on Apple File 
Exchange in the Macintosh Utilities User’s Guide before using this manual. 











About this manual 


The manual is organized as follows: 


Q Chapter 1 introduces Apple File Exchange and translators. It also lists the hardware 
and software you'll need to write translators. 


Q Chapter 2 tells how to design and write translators. It lists the tasks a translator must 
carry out and includes detailed reference information needed to implement a 
transiator. 


D Chapter 3 provides reference information for each of the messages sent from Apple 
File Exchange to translators. 


O Chapter 4 provides reference information for the ProDOS? file system calls that 
can be made from translators. 


o Chapter 5 provides reference information for the MS-DOS file system calls that can 
be made from translators. 


O Appendix A lists Pascal conventions for character strings, parameter passing, and 
register assignments. These conventions must be observed by translators written in 
programming languages other than Pascal. 
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Syntax notation used in this manual 
The following notation is used in descriptions of function and procedure calls: 


terminal Plain text indicates an element that must be entered exactly as shown. If 
there are special symbols (for example, + or /), they must also be 
entered exactly as shown. 


(a group) Parentheses group together elements. 


[optional] Square brackets indicate that the enclosed element or elements are 
optional. 


repeated... Three ellipsis points (...) indicate that the preceding element (or the 
preceding group of elements within parentheses or brackets) can be 
repeated one or more times. 


albic Vertical bars separate elements in a group from which a single element 
must be chosen. The elements are often grouped within parentheses or 
brackets. 


Throughout the manual, the Courier typeface is used to show sample programs and 
elements that appear in programs. 


Syntax notation used In this manual 
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O Appendix B lists Apple File Exchange diagnostic messages that are available for use 
by translators. 


o Appendix C provides an example of a translator. You can use this example as the 
starting point for a new translator. 


C Appendix D describes the differences between the U.S. and international versions 
of Apple File Exchange. 

C Appendix E lists the character transliterations performed by Apple File Exchange 
transliteration routines. 


At the end of the manual are a glossary and an index. Terms in the manual that are 
shown in boldface appear in the glossary. 











For more information 


You can find important related information in these manuals: 


O The Macintosh Utilities User's Guide includes two chapters that describe Apple File 
Exchange. These chapters, "Apple File Exchange" and "Apple File Exchange: 
Advanced Features," provide detailed information about using Apple File 
Exchange. You should be familiar with the information in these chapters before you 
begin writing translators. 

O Volumes I-IV of Inside Macintosh are the primary sources of information about 
the Macintosh Operating System and User Interface Toolbox routines. It is 
especially important that you be familiar with the routines described in the File 
Manager chapter in Volume IV. 

o The Macintosh Programmer’s Workshop Pascal Reference describes the version 
of Pascal used in the examples. 


In addition, the Apple Programmer's and Developer's Association (APDA) is an 
excellent source of technical information for anyone interested in developing Apple- 
compatible products. Membership in the association allows you to purchase Apple 
technical documentation, programming tools, and utilities. For information on 
membership fees, available products, and prices, please contact 


APDA 

290 SW 43 Street 
Renton, WA 98055 
(206) 251-6548 
Applelink: APDA 
MCI: 312-7449 
CompuServe #73527,27 
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Chapter 2 


Writing Translators 
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In this chapter, you'll be introduced to Apple File Exchange and learn the role 
translators play in converting files. In addition, you'll find information about the 
hardware and software you'll need to write translators. 











About Apple File Exchange 


Apple File Exchange is a Macintosh application that lets users 

O copy files and directories from one file system to another 

o convert files from one file format to another 

3 transliterate the characters in a file from one character set to another 

Apple File Exchange runs on any Macintosh that supports double-sided disks. It allows 
users to copy files between these file systems: 

a Macintosh 

Q ProDOS 

o MS-DOS 


For examples of what Apple File Exchange can do, see the chapters dealing with Apple 
File Exchange in the Macintosh Utilities User's Guide. 


Advantages of Apple File Exchange 


For developers writing translation routines, Apple File Exchange has important 

advantages over other file conversion utilities: 

D. It performs batch translation of dissimilar files. Files of different types can be 
translated in a single operation. 

ao It can move files between Macintosh disks, 800K ProDOS disks, and 5.25-inch 
MS-DOS disks. 


o It can be used with AppleShare™ File Server software. 


O It is generally available. A copy of Apple File Exchange is now included with every 
Macintosh and every drive card for Apple PC 5.25 drives. In addition, owners of 
earlier Macintosh personal computers can get Apple File Exchange as part of the 
Macintosh System Update Version 5.0. This update is a retail product that is 
available from Apple dealers. i 

Q It provides a consistent, easy-to-use user interface for all translations. 


C It provides a framework that allows quick development of new translation routines. 
Apple File Exchange handles the user interface and provides file system calls that 
are the same for ail file systems. This frees developers to concentrate on the actual 
file conversion. 
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Handling Apple File Exchange messages 


The job of a translator is to respond to messages from Apple File Exchange. There is a 
single function for all calls to a translator, which is of the form 


FUNCTION Translate (Message : integer; 
VAR TranslateData : longint; 
Param : longint; Self : handle) : 
longint; 


The Message parameter determines the task the translator performs in response to a 
call. The tasks performed by translators include 


O providing information on the current status of the translator 
o determining if the translator can translate a particular file 

CO giving a file a new name 

o translating a file 


Chapter 3, "Messages From Apple File Exchange to Translators," provides complete 
information about each of the messages. 


Calling Apple File Exchange routines 


To communicate information back to Apple File Exchange and, in turn, to the user, a 
translator calls routines that are part of Apple File Exchange. These routines enable a 
translator to 


C inform the user of the current status of a translation 

O puta message in the User Log 

D puta message in the User Log and, after all translations are complete, display a 
dialog box indicating that important information has been added to the User Log 


These routines are described in detail in the section “Calls From Translators to Apple 
File Exchange" later in this chapter. 


What transtators must do 
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Recognizing files 


Another of the tasks a translator must perform is deciding whether it can translate a 
file. Depending on the file system and the type of file, this task can either be simple or 
quite involved: 


C For translators that translate Macintosh files, recognizing a file usually involves no 
more than a look at the file type and creator for the file. 


C Translators that translate ProDOS files can often recognize a file by its file type and 
auxiliary file type. It may not, however, be as simple as this: because ProDOS has 
only 256 unique file types, applications may be forced to use the same file type for 
files with differing characteristics. 

D Translators for MS-DOS files face a more difficult task. Because there are no file 
types built into MS-DOS, translators often have to read a file and analyze its 
structure before deciding whether they can translate it. 


When designing a translator, you must decide what acceptance criteria the translator 
will use. Choose the criteria carefully: translators that attempt to translate the wrong 
files can destroy information, while translators that fail to recognize the files they 
should are frustrating for users. When in doubt, the translator should open a file and 
quickly search for characteristics that are unique to the kind of file it can translate. This 
search should be quick and efficient. Translators should not take the time to perform a 
trial translation of the entire file. The example that follows illustrates the design of one 
recognition algorithm. 


An example: Recognizing MS-DOS SYLK files 


Symbolic Link (SYLK) is a format used to represent files created by Microsoft 
Multiplan and other applications. SYLK files are made up of ASCII characters. They 
include these components: 


o Records are the fundamental building blocks of SYLK files. They begin with a one- 
or two-character record-type descriptor and end with a new-line separator. (On the 
Macintosh, a carriage-return character serves as the new-line separator. On other 
computers, a new-line separator may be a carriage-return character followed by a 
line-feed character.) ` 


O Fields are contained within records. They can begin with an optional field-type 
descriptor consisting of a semicolon (;) followed by a single character. 


Like other MS-DOS files, MS-DOS SYLK files do not have an explicit file type. 
Although MS-DOS filenames can have identifying extensions, these extensions can be 
altered and may not accurately reflect the contents of a file. To recognize an MS-DOS 
SYLK file, a translator must open the file and check to see if the first record is a SYLK 
ID record. An ID record begins with a record-type descriptor consisting of the 
character Jor { followed by D or d. The record contains the field descriptor ;P or ;p 
followed by the name of the program that produced the file. Like all SYLK records, the 
ID record must end with a new-line separator. (On the IBM PC, the new-line separator 
is a return character followed by a line feed.) If a file begins with this record, it is 
almost certain to be a SYLK file. 


What transiators must do 
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This chapter provides information you need to design and write translators. It includes 
o an overview of the tasks translators perform 

C reference information about translators 

o examples of translators 

Before beginning work on a translator, you should first become familiar with the ways 
in which people use translators. The Apple File Exchange chapters in the Macintosh 
Utilities User's Guide describe the tasks users perform when translating a file. Read 
these chapters and, if you haven't already, spend some time using Apple File 
Exchange before going on. 
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What translators must do 


This section gives an overview of the tasks that translators perform: 


1. They respond to calls from Apple File Exchange. These calls request specific 
services or pass information to the translator. 


2. They call routines in Apple File Exchange to communicate information back to the 
user. 


3. They make file system calls to read and write files and to perform other file 
operations. 


4. When necessary, they call transliteration routines (TProcs) to convert the 
characters in a file to another character set. 


5. They determine if they can translate a particular file. 
6. They respond appropriately when moved to other Apple File Exchange menus. 


In addition, Apple File Exchange makes its own calls to file systems. Figure 2-1 
illustrates the calls that occur during Apple File Exchange operation. 
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Figure 2-1 
Relationship between Apple File Exchange. translators, file systems, and TProcs 
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Selecting a name for a translator 


There are two points to remember when choosing a name for a translator: 


O The name you choose for the translator resource is the name that appears in the 
translator menu. 

C If selecting a translator's menu item causes a dialog box to appear, be sure to 
include three ellipsis points (...) at the end of the menu item's name. To type the 
ellipsis poinrs, which on the Macintosh are a single character, hold down the 
Option key while you press the semicolon C) key. 





Designing dialog boxes 
Keep the following suggestions in mind when designing dialog boxes for a transiator: 


o Dialog boxes for translators must be modal; that is, the user must click a button to 
close them before doing anything else. 


C Dialog boxes should not be too big. If there are too many items for a single dialog 
box, provide one dialog box that includes the most frequently selected options, 
and one or more additional dialog boxes for options that are less frequently 
selected. 

O When labeling the options in a dialog box, use terms that describe what the user 
sees, not terms that describe the internal details of a file. For example, a button 
labeled "Ignore Left Margin Commands" is preferable to one labeled 
“Ignore .LM"*. 





Designing About boxes 


An About box is a dialog box that provides information about a particular translator. 
Users can view an About box by choosing the About Apple File Exchange item from 
the Apple menu, selecting the name of a translator in the dialog box that appears, 
then clicking the About button in the dialog box. An About box should contain 


CO the name of the translator and any relevant copyright information 

o a description of the translator and any options the translator provides 

O the author(s) of the translator 

O the version number of the translator and the date the translator was written 


You can create an About box for a translator in one of two ways: 


o You can include text for the About box in a resource. Apple File Exchange then 
takes this text and displays it in a dialog box that includes a scroll bar and an OK 
button. This is the simplest approach, but it does not provide any control over the 
font, type size, or type style used for the text. 


O You can create your own About dialog box for the translator. This approach gives 
you control over the fonts, type sizes, and type styles used for the text, and, in 
addition, allows you to include additional buttons and graphics within the dialog 
box. The About box must be a moda! dialog box (that is, one the user must close by 
clicking a button before doing anything else). 
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Calling file systems 


To perform operations involving files, translators call file system routines. Apple 
File Exchange supports these file systems: 

O Macintosh Hierarchical File System (HFS) 

o ProDOS 

G MS-DOS 

The operations performed by file system routines include 

C opening, reading, and writing files 

O creating, renaming, and deleting files 

o allocating memory for files 

C reading and changing file and volume information 


To perform operations involving file systems, translators use the function CallFS: 


FUNCTION CallFS (msg : integer; fsdata : Ptr; 
pb : Ptr; async : boolean; 
fsroutine : handle) : OSErr; 


CallFS provides a single, uniform interface to all the file systems supported by Apple 
File Exchange. The fsroutine and fsdata parameters select the file system, while the 
msg parameter indicates the operation to perform. 


Apple File Exchange file systems are stored as resources. The operations they perform 
parallel those provided by the Macintosh file system wherever possible. The section 
"Calls From Translators to File Systems" later in this chapter provides details about 
calls to file systems, while Chapters 4 and 5 describe the differences between file 
system calls and their HFS counterparts. 
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Converting character sets 


When a translator moves a file containing text to a computer, file system, or 
application that uses a different character set, it must convert the representation of 
each character in the file to the representation used in another character set. This 
process of converting characters is called tvansitteration. Here is an example: on a 
French member of the Apple II family, the character d is represented by the 
hexadecimal number 40, while on the Macintosh 2 is represented by the hexadecimal 
number 88. When moving the character d from a French Apple II to a Macintosh, a 
translator calls a transliteration routine that changes its representation from 40 
hexadecimal to 88 hexadecimal. 


To perform most transliterations, translators use transliteration resources known as 
TProcs that are provided with Apple File Exchange. Each international version of the 
Macintosh includes a set of TProcs, known as a TProc family, for transliterating files 
between different computers used in the same country. For example, the TProcs 
included with a French Macintosh transliterate files between French versions of the 
Macintosh, Apple II, and IBM PC, while the TProcs included with an Italian 
Macintosh transliterate files between Italian versions of the Macintosh, Apple II, and 
IBM PC. To perform transliterations for which there are no TProcs, such as 
transliterations from one language to another or transliterations of files that use 
special character sets, translators must provide their own uansliteration procedures. 
For details about calling TProcs, see the section “Calls From Translators to 
Transliteration Routines" later in this chapter. 
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Resource types for translators 


The resource type for a translator is determined by the source and destination file 
systems for the files it translates. These resource types, which are built out of two-letter 
abbreviations for each file system, are listed in Table 2-1. 








Table 2-1 

Resource types for translators 

Source file Destination tile Transiater resource 
system system type 
Macintosh Macintosh 'MCMC' 
Macintosh ProDOS 'MCPD' 
Macintosh MS-DOS 'PDMS' 
ProDOS Macintosh 'PDMC' 
ProDOS ProDOS 'PDPD' 
ProDOS MS-DOS 'PDMS' 
MS-DOS Macintosh 'MSMC' 
MS-DOS ProDOS 'MSPD' 
MS-DOS MS-DOS 'MSMS' 


For example, a translator that converts MacWrite® files from a Macintosh disk to 
Apple Works? word processing files on an Apple II disk would have the resource type 
'MCPD'. 





Transiator resources and menus 


In addition to a resource type, each translator resource has a resource name and a 
resource ID. These resource IDs must be multiples of 25. The resource name is used as 
the translator's item name in translator menus. The resource ID determines a 
translator's position in translator menus: 


© Translators with resource IDs greater than 2000 are special-purpose translators. 
These transiators are used in cases where either the source-file format or the 
destination-file format is used by a limited range of applications. Except in very 
rare cases, translators written by suppliers other than Apple will be special-purpose 
translators. Their menu items appear in the top part of translator menus and are 
arranged alphabetically. 


O Translators with resource IDs less than or equal to 2000 are general-purpose 
translators. These translators convert file formats used by a wide variety of 
applications to other widely used formats. One example is a translator that converts 
text files from one file system to equivalent text files on another file system. Another 
example would be a translator for encrypting files. Except in very rare cases, the 
only general-purpose translators will be those that are built into Apple File 
Exchange. Their menu items appear in the bottom part of menus and are arranged 
in order of their ID numbers, with translators that have higher-numbered IDs closer 
to the top. 


4 Note: The resource ID 0 is reserved for default translators. Default translators are 
always provided by Apple File Exchange; do not use the resource ID 0 for 
translators you write. 
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Handling moves to other menus 


Special-purpose translators—the translators that appear in the top part of translator 
menus—can be imported to other menus through the use of the Other Translations 
menu item. (Except in very rare cases, translators writen by suppliers other than 
Apple will be special-purpose translators. Special-purpose translators are discussed in 
greater detail in the section “Translator Resources and Menus” later in this chapter.) 
Because special-purpose translators can be imported, they must be able to handle 
translations berween other file systems when appropriate. Normally, any special- 
purpose transiator should handle translations when the source or destination file 
systems are the same as either of the file systems in the original menu. For example, a 
translator from the ProDOS to Mac menu should work when imported to the ProDOS 
to ProDOS or Mac to Mac menus, but it need not work in the ProDOS to MS-DOS or 
MS-DOS to MS-DOS menus. 


Translators must never crash when imported to another menu. If a translator cannot 
translate files between the new menu’s two file systems, it must inform the user with an 
alert or an entry in the User Log. 


In re ġ 
Designing a translator's user interface 
The following sections provide guidelines for designing a translator's user interface. 


For additional information, refer to "The Macintosh User Interface Guidelines" 
chapters in Volumes I and IV of Inside Macintosh. 


i MÀ 
Remember your audience 

When you design a translator, consider the diversity of your audience: 

O Many Apple File Exchange users will be using the Macintosh for the first time. 


o Many Apple File Exchange users will normally use a computer other than the 
Macintosh. Apple File Exchange will often be the only Macintosh application they 
use, and they'll be reluctant to learn more about the Macintosh than they have to. 

o Others will be experienced Macintosh users, but they'll be unfamiliar with the 
terminology used to describe ProDOS and MS-DOS files. 

© Among the people who use a particular translator, some may know a great deal 
about the files they're translating, while others may know nothing at all about the 
files or the application used to create them. 


The best advice is to keep a translators user interface simple, and to make as few 
assumptions about your audience as you can. 
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Declaring translators 


Translators are functions that are called by Apple File Exchange. To declare a 
translator function, use a declaration of the form 


FUNCTION Translate (Message : integer; 
VAR TranslateData : longint; 
Param : logint; Self : 
handle) : longint; 


The name you choose for a translator function is up to you. The translator parameters 
are described in the following sections. 





Translator parameters 
The following sections describe the parameters to translator functions. 


The Message parameter 


The Message parameter identifies the operation to be performed by the translator. 
Table 2-3 lists the possible values for Message together with constant identifiers and 
meanings for each value. 


Table 2-3 | 

Values for the Message parame 

Constant identifier aa Meaning 

trn_About 12 Provide information about the translator 

trn_Activate 4 Activate (check) the menu item for the translator 

trn_Appear 9 Activate translator when the translators menu item appears in a 
menu and change apearance of menu item if necessary 

trn_Deactivate 5 Deactivate (uncheck) the menu item for the translator 

trn_Disappear 10 Perform any actions needed (such as freeing memory) when a menu 
containing the translator's menu item disappears 

trn_Finis 1 Perform any cleanup needed before exiting 

trn_File F Translate the file 

trn_Get 2 Return current status of translator 

trn_GetSettings 13 Get the settings for the translator 

trn_Init 0 Initialize translator 

trn_Load 11 Load resources used by the translator 

trn_NewName 6 Retum a new name for a file 

trn_Recognize 8 Determine if translator can translate a file 

trn, Set 3 Set status of translator 

un SetSettings 14 Set the settings for the translator 


Complete information about each message is included in Chapter 3, "Messages From 
Apple File Exchange to Translators." 


Declaring translators 











Translators as resources 


Translators are stored as resources. These resources contain the code and other 
information necessary to perform translations. Apple File Exchange calls a translator 
by loading the translator resource into memory, then jumping to the first instruction 
in the resource. 


Translator resources normally reside in translator files. The only exceptions are 
resources for the translators built into Apple File Exchange, which are part of the 
Apple File Exchange program. Translator files can contain one or more translator 
resources. When opened, Apple File Exchange opens any translator files it finds in the 
Apple File Exchange folder. Other translator files can be kept in other folders and 
moved into the Apple File Exchange folder when needed. 


€ Note: The Macintosh operating system puts limits on the number of resource files 
an application can have open. For example, Apple File Exchange running on the 
Macintosh Plus can have a maximum of 14 translator files open at the same time. 
This means that if you put several translators together in the same file, users can 
have more translators available in translator menus. If there are fewer translators in 
a translator file, moving the file into or out of the folder containing Apple File 
Exchange affects the availability of fewer translators. 


How do you decide which translators to put in a translator file? In general, you 
should put any translators that are related in the same file. For example, it is a good 
idea to keep a translator and its reverse translator (for example, the translators 
MySpreadsheet to YourSpreadsheet and YourSpreadsheet to MySpreadsheet) 
together in the same translator file. 


The file type of translator files is 'VISA'. The creator for translator files can be either 
'PSPT' or a unique, four-byte creator type. 


€ Note: If the creator of a translator is 'PSPT', the icon for the translator is provided 
by Apple File Exchange. Assigning the translator a unique creator type allows the 
translator to have its own unique icon. (To ensure that a new creator type is unique, 
you must register the type with Macintosh Technical Support.) For information on 
creating an icon for a translator, see the section "Customizing Icons" later in this 
chapter. 
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Table 2-4 (continued) 
Transiator status flags 








Name Bit number Use 

Outline 7 Set this flag if the menu item for the translator is to 
appear in outlined characters. 

Shadow 8 Set this flag if the menu item for the translator is to 
appear in shadowed characters. 

About 9 Set this flag if information about the translator is 
available for display in an About box. 

(Reserved) 10-11 Reserved for future use. Set these bits to 0. 

(Translator bits) 12-14 Bits reserved for use by the translator. These bits will 
never be used by Apple File Exchange. 

(Reserved) 15 Reserved for Apple File Exchange. 

(Unused) 16-31 These bits may be used by future versions of Apple 


File Exchange. Use these bits only if necessary; to 
ensure complete compatibility with future versions 
of Apple File Exchange, set these bits to O. 


“When the trn, Set message is sent to a default translator, Apple File Exchange sets the 
Active flag for the translator. 

tWhen a translator returns an error in response to a tm_Appear message, Apple File Exchange 
clears the translator's Active flag. 

‘When a translator returns an error in response to a trn Appear message, Apple Pile Exchange 
sets the translator's Gray flag. 


Figure 2-4 gives Pascal constant definitions for the status flags. 


CONST 
trnActive = $0001; 
trnGray = $0002; 
trnBold = $0010; 
trnitalic = $0020; 
trnUnderline = $0040; 
trnOutline = $0080; 
trnShadow - $0100; 
trnAbout = $0200; 

Figure 2-4 


Pascal constant definitions for status flags 


The Param parameter 


The value of the Message parameter sent to a translator determines how the Param 

parameter is used: 

C It can be ignored. 

O It can be used for long-word values such as the translator status. 

Cl It can be used as a pointer to the translation parameter block. The contents of 
the translation parameter block are described later in this chapter. 


The way in which Param is used with each message is described in Chapter 3, 
"Messages From Apple File Exchange to Translators." 
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General-purpose translators have two important limitations that distinguish them 
from special-purpose translators: 


o They cannot be imported to other menus. 


C In the dialog box that allows the user to select a translator when more than one 
translator can translate a file, general-purpose translators are not shown. A 
general-purpose translator is not chosen by the user, but is instead used 
automatically when no special-purpose translators can translate a file. It is assumed 
that one or more of the general-purpose translators can translate any file. 


© Note: Include a translator among the general-purpose translators only if it is truly 
general-purpose. Neverinclude a translator among the general-purpose 
translators merely to keep it from being imported to another menu. If a translator 
does not accept and create files that can be used by many different applications, it 
should appear with the special-purpose translators. 


Table 2-2 lists resource types, resources IDs, and names for sample resources. 

Figure 2-2 shows the translator menus that result. These menus illustrate how resource 
types, IDs, and names for translators affect translator menus. In the menus, note the 
following: 


D Translators of resource type 'PDMC' appear in the ProDOS to Mac menu, while 
translators with resource type 'MCPD' appear in the Mac to ProDOS menu. 


o If ellipsis points (...) are part of the resource name, they appear in the menu. 
Ellipsis points indicate that a dialog box appears when the user selects the menu 
item. 


Table 2-2 
‘Sample transiator resources 


Resource type Resource ID Resource name 


'PDMC' 7300 Applesoft to MS-Basic 
'PDMC' 2325 Apple Works to Excel 
'PDMC' 15000 VisiCalc to SYLK... 
'PDMC' 12000 TXT to MDS 

'PDMC' 1100 TXT to TEXT 

'PDMC' 0 Default transiation 
'MCPD' 2700 MacWrite to AppleWorks 
'MCPD' 3500 MultiPlan to VisiCalc... 
'MCPD' 1000 TEXT to TXT 

'MCPD' 0 Default translation 







Mac to Provas 


+ Macitrite to AppleWorks 
A MuiltiPian te BisiCalc... 


X TENT to FHT 
è Default translation 
athar Jrans/at/onms... 


ProDos to Mat 


X fipplesoft te MS-Basic 
X fipplellJorks te Excel 
X UlsiCaic to SYTLK ... 


X THT to MDS 


A THT to TENT 
* Befauit translation 
Sibert Mansia tios 





Figure 2-2 
Translator menus for the tansators in Table 2-2 
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Type declaration for the translation parameter biock 
Figure 2-5 shows a Pascal type declaration for the translation parameter block. 


TYPE TranslateRec * RECORD 


trnLogProc 


trnStatProc 


trnFrID 


trnToID 


trnFrData 


trnToData 


trnResrv 


trnFrVRef 


trnToVRef 


trnFrPar 


trnToPar 


trnNames 


trnTested 


trnAccepted 


trnCountry 


END; 


TrnPtr = ^TranslateRec; 


Figure 2-5 


.* 


ee 


procPtr; 


procPtr; 


integer; 


integer; 


Ptr; 


Ptr; 


integer; 


integer; 


integer; 


longint; 


longint; 


nameBdl; 


Boolean; 


Boolean; 


integer 


(Pointer to the Log procedure) 


(Pointer to the Status 
procedure) 


(Resource ID of the source 
file system) 


(Resource ID of the 
destination file system) 


(Pointer to global data for 
the source file system) 


{Pointer to global data for 
the destination file system] 


(Used by Apple File 
Exchange) 


(Volume reference for 
source file} 


{Volume reference for 
destination file} 


(Parent ID for source file) 


(Parent ID for destination 
file) 


(Handle to names of source 
and destination files) 


(TRUE 1f the translator has 
already tried to recognize 
a file) 


(If trnTested is also TRUE, 
TRUE indicates that the 
file was recognized) 


(The country code for the 
Macintosh on which Apple 
File Exchange is running } 


Type declaration for the transiation parameter block 
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The TranslateData parameter 


The TranslateData parameter is used for a translators global data. It can be used to 
store 


C a 32-bit long word that contains the status flags for the translator 


a a handle to global data for a translator that requires more than four bytes of global 
data 


Storing the translator's status is the most common use for TranslateData. The status 
flags are shown in Figure 2-3. 


gre PEE — 


Reserved | 
Transiator bits TTT] 
Reserved: Must be 0 
About 
Shadow 
Outine 
Underline 
Italic 
Bold 
Figure 2-3 


Translator status 


Table 2-4 lists the uses of each of the status flags. 


Table 2-4 

Translator status flags 

B a 

Name Bit number Use 

e—a 

Active 0 Set this flag if the translator is active. (The menu 
items for active translators are checked or, in the 
case of default translators, marked with a diamond. 
A translator should normally be active when users 
start up Apple File Exchange.)*t 

Gray 1 Set this flag if the translator is disabled. (Menu items 
for disabled translators are shown in gray.)+ 

(Reserved) 2-3 Reserved for future use. Set these bits to 0. 

Bold 4 Set this flag if the menu item for the translator is to 
appear in bold characters. 

Italic 5 Set this flag if the menu item for the translator is to 
appear in italic characters. 

Underline 6 Set this flag if the menu item for the translator is to 


appear in underlined characters. 
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trnTested: This field indicates whether the translator has already been sent a 
un Recognize message for a file. If the value of the field is TRUE, the translator does 
not have to determine again if it can translate the file. 


tmToData: This field contains a pointer to global data for the destination file system. 
trnToID: This field contains the resource ID for the destination file system. 
tmToPar: This field contains the ID for the destination directory. 


trnfoVRef: This field contains the volume reference number for the destination 
volume. 





Headers for translators 
All translators must have assembly-language headers of the type shown in 








Table 2-5. 
Table 2-5 
Format for translator headers 
Offset Length 
In bytes Contents Description 
0 4 Fither Assembly-language instruction to 
BRA start branch around header’ 
or 
BRA.S start 
folowed by $00 
4 4 $7472616E Signature (ASCII ‘tran, which 
indicates that this is a transiator with a 
headert 
8 ID number Same as Resource ID number 
10 2 Version number Can be used to keep a version number 
for the translator 
12 nt Version A Pascal-type string’ for keeping a 
version identifier for the translator 
(for example, *V1.0B") 
12*n 4 $0000FFFF Reserved 
16+n 4 $00000000 Reserved 
20 +n m Tables, constants Static variables used by the translator 
20+n+m start label Label for beginning of translator 


*If a header begins with the BRA.S instruction, the total length of the header cannot exceed 
128 bytes. 

{Translators written for earlier, prerelease versions of Apple File Exchange did not have 
headers. 

fThe total number of bytes in this field (including the length byte) must be even. 

§Pascaltype strings have the length of the string as the first byte. (For example, the first 
byte of the string “V1.0B" would contain the number 5.) 
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The Self parameter 


The Self parameter is a handle to the memory location where the translator resides. 
This permits the translator to lock itself down (through a call to the Memory Manager 
HLock routine with Self as a parameter) and thus prevents the translator from being 
moved or purged. The parameter can also be used in the following ways: 


o It allows the translator to change its memory attributes (such as whether it is locked 
or purgable) when exiting. 


© it makes it possible for the translator to get resource information about itself. The 
translator can then use this information when obtaining other resources. 





Results retumed by translators 


Translators return results only in response to certain messages from Apple File 
Exchange. The descriptions in Chapter 3, “Messages From Appie File Exchange to 
Translators," indicate when a message requires a particular result. When no result is 
required, a translator must return O. 





The translation parameter block 


With certain messages, Apple File Exchange provides a pointer to a translation 
parameter block. The exact contents of the parameter block depend on the operation 
to be performed. The block can contain a variety of information, including 


o the source and destination file systems for a translation 

C source and destination directories 

Q names of files to be translated 

C pointers to procedures that can be called by the translator 


The descriptions in Chapter 3, "Messages From Apple File Exchange to Translators," 
indicate when a parameter block is sent with a message and describes the contents of 
the block. 
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When you design a translator, pay special attention to the text of error messages: 

O Be specific. Let users know exactly what caused the problem. 

o Use terms all users will understand. Avoid terms that are specific to a particular 
application or file system. | 

o Be complete. Use as many characters as you need to produce descriptive, helpful 
messages. 


4 Note: When transiating more than one file, Apple File Exchange does not stop 
when an error occurs. Because of this, it is essential that translators record errors in 
the User Log. 





Including other information in the User Log 


Translators can use the User Log to communicate other information that's of interest 
to users. For example, translators can note when any characteristics of a document, 
such as the format or fonts used, are changed during translation. Once again, 
consider the needs of your audience: if something happens that affects what users can 
do with a translated file, put a message in the User Log. 





indenting messages 


When Apple File Exchange translates nested files and folders, the User Log can show 
the nesting by indenting entries. Figure 2-7 shows an example of indentation within the 
User Log. 


Copying Mac to Mac, 7/29/87, 10:59:24 AM 


APS 2.0 --» APS 2.0 {Folder} 
1-Column Glossary 2.0 --» 1-Column Glossary 2.0 (Default translation} 
l-Column Template 2.0 --» 1-Column Template 2.0 (Default translation} 
2-Column Glossary 2.0 --» 2-Column Glossary 2.0 (Default translation} 
2-Column Template 2.0 --» 2-Column Template 2.0 (Default translation} 


Figure 2-7 
indentation within the User Log 


Translators can control whether indentation occurs. Entries associated with a 
particular file should normally be indented; indenting the entries causes them to 
appear immediately above or below the User Log entry for the file. There are, 
however, cases where you may want to tum off the indentation for an entry. For 
example, suppose a translator for a word-processing document informs the user that a 
footnote cannot be translated, then lists the text of the footnote in the User Log. By 
turning off indentation for the footnote listing, the translator can make it easier for the 
user to copy the footnote from the User Log and paste it into the newly translated 
document. 
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Contents of the translation parameter block 
This section describes each of the fields in a translation parameter block. 


tmAccepted: If the trnTested field is TRUE, this field indicates whether a file was 
accepted for translation. 


trnCountry: This field contains the country code for the Macintosh system software 
under which Apple File Exchange is running. When transliterating files, translators use 
the country code to identify the source and destination character sets. Current country 
codes and their meanings are listed in the International Utilities Package chapter in 
Volume 1 of Inside Macintosh. 


tmFrData: This field contains a pointer to global data for the source file system. 
tmFriD: This field contains the resource ID for the source file system. 

frnfrPar: This field contains the ID for the source directory. 

tmFrVRef: This field contains the volume reference number for the source volume. 


irnLogProc: This field contains a pointer to the User Log procedures CallLog and 
CallErrLog. Translators call these procedures to inform the user of errors and other 
events. For a complete description of these procedures, see the section “Calls From 
Translators to Apple File Exchange" in this chapter. 


trmNames: This field contains a handle to the names of the source and destination 
files. The names are stored in a NameRec record. Figure 2-6 shows a Pascal type 
definition for the NameRec record. 


CONST maxdestnames = 1; 

TYPE NameRec = RECORD 
nameCnt : integer; (Number of destination files) 
name ; array[O..maxdestnames] of str255 


(Names of source and destination files: name[O0] contains the name 
of the source file, while name(1] contains the name of the 
destination file. Future releases of Apple File Exchange may 
support multiple destination files.) 


END; 

NamePtr = ^NameRec; 

NameHdl = ^NamePtr; 

Figure 2-6 

The NameRec record 

trnResrv: This field is reserved for use by Apple File Exchange. 


trnStatProe: This field contains a pointer to the Apple File Exchange status 
procedure. Translators call this procedure to inform the user of a translation's current 
status. For a complete description of the procedure, see the section “Calls From 
Translators to Apple File Exchange" in this chapter. 
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Input 


Output 


Notes 


Example 


See also 


The input parameters for the CallErrLog procedure are 


Su A Pascal-type string that contains a description of an error or 
information about another event of interest to the user. (Pascal- 
type strings have as their first byte the number of characters in the 
string; for example, the string "LONG" has 4 as its first byte.) The 
string can contain up to 255 characters. 


CR TRUE if the description in Str is to be followed by a carriage return; 
FALSE if not. 

Indent TRUE if the description in Str is to be indented to reflect the nesting 
of the file or directory being translated; FALSE otherwise. 

LogProc >- A pointer to the CallErrLog procedure. The translator must get this 
pointer from the trnLogProc field of the translation parameter 
biock. 

None. 


The alert box informing the user about an error appears immediately after all 
translations are complete, not during the translations. 


CallErrLog should be used to log errors and other unexpected events. CallLog can be 
used to put any other information in the User Log. 


Although translators may call CallErrLog more than once when translating files, only 
one alert box appears when the translations are finished. 


If the message you want to send is longer than 255 characters, simply call CallErrLog . 
or CallLog as many times as necessary to send the entire message. 


CallErrLog (MyString, TRUE, TRUE, MyData^.trnLogProc); 


puts the message in MyString in the User Log and requests that the message be 
indented as necessary to reflect the nesting of the file being translated. The alert box 
contains the message ‘An error occurred during the translation. Please check the 
User Log for more information." 


The descriptions of the un File message and the CallLog procedure. 
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Calls from translators to Apple File Exchange 


Apple File Exchange provides three routines that can be called by transiators. 
Translators use these routines to 2 


D inform users about the status of a translation 
C send error messages and other messages to users 


Table 2-6 lists the routines and their uses. 


Table 2-6 
Cails to Apple File Exchange 


Routine Description 


CallErrLog Enters a message in the User Log and displays an alert box telling the 
user that there is an addition to the User Log 


CallLog Enters a message in the User Log 
CaliStat Provides information about the status of a translation 


Because translators are stored as resources that are separate from Apple File 
Exchange, they cannot call Apple File Exchange routines through normal Pascal 
calling conventions. When making calls from translators written in Pascal to these 
routines, translators must circumvent the normal flow of control through the use of 
inline machine instructions. The MPW Pascal INLINE directive (or the equivalent 
technique in other languages) allows translators to replace the JSR assembly-language 
instruction that concludes normal MPW Pascal routines with other instructions, 
making these cails possible. 


The machine-language instructions used for each call to an Apple File Exchange - 
routine are described with the routine. For information on Pascal calling conventions, 

see Appendix A, "Pascal Conventions for Translators." For information on the 

INLINE directive, see the Macintosh Programmer's Workshop Pascal Reference. 
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Logging errors 


A translator must put an error message in the User Log whenever it fails to translate a 
file. It should also log other problems that it encounters if the information may be 
useful to users. It is important to include an explanation of why the error occurred. 
Some errors result from problems outside the control of the translator, such as 
input/output errors, while other errors are the result of problems within the translator. 


Apple File Exchange provides two different procedures for logging messages: 
CallErrLog and CallLog. After all translations are complete, CallErrLog displays a 


dialog box informing the user that an error has occurred. CallLog does not display a 
dialog box. 


2-18 Chapter 2: Writing Translators 


Notes 
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CaliErrLog should be used to log errors and other unexpected events. CallLog can be 
used to put any other information in the User Log. This information can include 
changes to any file components (for example, fonts) that occur during translation, 
and information about a translation specifically requested by the user. 


If the message you want to send is longer than 255 characters, simply call CallLog as 
many times as necessary to send the entire message. 


CallLog (MyString, TRUE, TRUE, MyData^.trnLogProc); 
puts the message in MySuing in the User Log and foilows it by a carriage return. In 


addition, it requests that the message be indented as necessary to reflect the nesting of 
the file being translated. 


The descriptions of the trn, File message and the CallErrLog procedure. 
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CallErLog—adds an error message to the User Log 


Description The CallErrLog procedure allows a translator to put error messages and other 
information in the User Log. Unlike CallLog, calling CallErrLog causes an alert box to 
be displayed after all translations are finished. The alert box contains the message 
*An error occurred during the translation. Please check the User Log for more 
information." 


When called The CallErrLog procedure must be called whenever an error occurs during a 
translation. 


Declaration Procedure CallErrLog (Str : str255; CR : Boolean; Indent : Boolean; 
LogProc : procptr); 


INLINE $205F, S1FSF, $0001, $002F, $0080, $0001, S$4E90; 


The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 


; Pop the address of the log procedure off the stack 

; and put it AO 

MOVE.L (A7) *, AO 

; Pop the Indent parameter off the stack and put it in the 
; byte after the CR parameter on the stack 

MOVE.B (A7) *, 1(A7) 

; Change the flag that indicates that this is a CallErrLog 
; call rather than a CallLog call. (The address of these 
; two calls is the same.) 

ORI.B 8580, i1(SP) 

; Use the JSR instruction to push a return address 

: on the stack and then jump to the log procedure 

; pointed to by A0 


JSR (AO) 
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CallStat—informs the user of a translator's progress 


With the CallStat function, a translator can inform the user about the progress of a 
translation. Translators provide the CallStat function with 


O a string describing the operation taking place 
O a percent-complete value for the translation 


Apple File Exchange then displays the string together with a bar graph showing the 
percent-complete value. 


The CallStat function must be called periodically during the actual translation of a file 
(that is, after the translator receives the trn. File message from Apple File Exchange 
and accepts the file to be translated). 


Function CaliStat (StatMsg : str255; StatPct : integer; DestFNum : integer; 
StatProc : procptr) : Booiean; 


INLINE $205F, $4E90; 


The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 


; Pop the address of the CallStatus function off the stack 

; and put it AC) 

MOVE.L (A7) *, AO 

; Use the JSR (Jump to Subroutine) instruction to push a 

; return address on the stack and then jump to the CallStatus 
; function pointed to by AO 


JSR (A0) 


The input parameters for the CallStat function are 


StatMsg A Pascal-type string that is displayed by Apple File Exchange during 
the translation. (Pascal-type strings have as their first byte the 
number of characters in the string; for example, the string "LONG" 
has 4 as its first byte.) 


StatPct An integer between 0 and 100 that indicates the progress of the 
translation. 


DestFNum Contains the value 1. 


StatProc A pointer to the CallStatus function. The translator must get this 
pointer from the trnStatProc field of the translation parameter 
block. 


The CallStat function returns the function result FALSE if the user has clicked the 
Cancel button. The function result TRUE indicates that the translator can continue. 
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Calllog—adds a message to the User Log 


Description The CallLog procedure allows a translator to put messages and other information in 
the User Log. 


When called The CallLog procedure should be called whenever an event occurs during a 
translation that may be useful for the user to know about 


Declaration Procedure CallLog (Str : str255; CR : Boolean; Indent : Boolean; 
LogProc : procptr); 


INLINE $205F, $1F5F, $0001, $4£90; 


The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 


; Pop the address of the CallLog procedure off the stack 

; and put it AO 

MOVE.L (A7) *, AO 

; Pop the Indent parameter off the stack and put it in the 
; byte after the CR parameter on the stack 

MOVE.B (A7) *, 1(A7) 

: Use the JSR (Jump to Subroutine) instruction to push a 

: return address on the stack and then jump to the CallLog 


; procedure pointed to by AO 


JSR (A0) 
input The input parameters for the CallLog procedure are 
Str A Pascal-type string that contains the message to be logged. 


(Pascal-type strings have as their first byte the number of characters 
in the string; for example, the string "LONG" has 4 as its first byte.) 
The string can contain up to 255 characters. 


CR TRUE if the description in Str is to be followed by a carriage return; 
FALSE if not. 

Indent TRUE if the description in Str is to be indented to reflect the nesting 
of the file or directory being translated; FALSE otherwise. 

LogProc A pointer to the CallLog procedure. Translators can get this pointer 


from the trnLogProc field of the translation parameter block. 


Output None. 
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Calls from translators to file systems 


To perform operations involving files, translators call file system routines. For both 
the Macintosh Hierarchical File System CHFS) and other file systems (known as 
foreign file systems), translators use the CallFS function described below. 


€ Note: While it is possible for translators to call HFS and other file system routines 
directly, translators should instead use the CallFS function. Apple File Exchange 
relies on the CallFS interface to properly handle certain events, such as the 
swapping of disks. 





File systerns as resources 


The CaliFS function provides a single, uniform interface to file systems. It does this by 
providing access to file system resources. Apple File Exchange provides a file 
system resource for each of the file systems it supports. Calls to the Macintosh file 
system resource are identical to the HFS calls described in "The File Manager" chapter 
in Volume IV of Inside Macintosh. Chapters 4 and 5 describe the calls available for 
the ProDOS and MS-DOS file systems. 


File system resources for file systems other than the Macintosh—those for ProDOS 
and MS-DOS—are called foreign file systems. The calls for these file systems are 
modeled on the corresponding Macintosh HFS calls. Many calls are identical for all 
file systems. For example, you can use the same FFClose call to close Macintosh, 
ProDOS, and MS-DOS files. There are, however, differences between many calls that 
reflect differences in the file systems. These differences are described in Chapters 4 
and 5. 


File systems are kept in resources whose type is '4NFS'. Because these resources are 
separate from translator resources, translators cannot make calls to file systems 
resources through normal Pascal calling conventions. As with Apple File Exchange 
routines, translators written in Pascal must circumvent the normal flow of control 
through the use of inline machine instructions. The MPW Pascal INLINE directive (or 
the equivalent technique in other languages) allows translators to replace the JSR 
assembly-language instruction that concludes normal MPW Pascal routines with other 
instructions, making these calls possible. 


The machine-language instructions used for the CallFS function are described with the 
function. For information on Pascal calling conventions, see Appendix A, "Pascal 
Conventions for Translators." For information on the INLINE directive, see the 
Macintosh Programmer's Workshop Pascal Reference. 
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Reporting the progress of a translation 


While translating a file, a translator must periodically use the CallStat function to 
inform the user of the progress it's making. The user sees this progress as a percent- 
complete value in a thermometer, as shown in Figure 2-8. 


ah 25% S0% 75% 100% 


Figure 2-8 
Status thermometer 


The accuracy of the reporting will inevitably be different for different translators. As 
you design a translator, keep in mind these points: 
O The thermometer display should begin at 0 for each file translated. 


Cl As a minimum, the thermometer should indicate that the translator is making 
progress during a translation. Any change in the thermometer readings will let the 
user know that the translator is working, 


o Ideally, the thermometer will indicate how much more time the translation will 
take. For example, if the change from 0 percent to 25 percent took 10 seconds, the 
time it takes to go from 25 percent to 100 percent should be as close to 30 seconds as 
possible. Achieving a reasonable level of accuracy may be difficult, but it is worth 
the effort. 
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CallFS—calls a file system routine 
The CallFS function allows a translator to perform operations involving a file system. 


The CallFS function is called whenever a translator needs to perform a file system 
operation, including such operations as creating, renaming, reading, and writing 
files. The description of the Msg parameter in Table 2-7 lists all of the possible 
operations. 


Function CallFS (Msg : integer; FSData : ptr; PB : ptr; 
Async : Boolean; FSRoutine : handle) : OSErr; 


INLINE $2057, $2050, $4E90; 


The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 


; Get the handle to the file system from the stack 

; and put it in register A0 

MOVE.L (A7), AO 

; Dereference the handle to get the pointer to the file 
; system; put the pointer in register AO 

MOVE.L (A0), AO 

; Use the JSR (Jump to Subroutine) instruction to push a 
; return address on the stack and then jump to the file 
; system pointed to by AO 

JSR (AQ) 


The input parameters for the CallFS function are 


Msg Identifies the desired operation. Table 2-7 lists file system 
operations and their corresponding Msg values. 


FSData A pointer to the global data for this file system. 


PB Usually a pointer to a parameter block used for the call. See 
Chapters 4 and 5 for the parameter block pointed to for each call. 


Async TRUE if the operation is to be performed asynchronously. This 
parameter applies only to operations that support asynchronous 
Operation. 


Note: The ProDOS and MS-DOS file systems do not support 
asynchronous operation. 


FSRoutine A handle to the resource containing the file system. 
The CallFS function returns an Operating System result code as the function result. If 


the result is noErr (= 0), the operation was completed successfully. 
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Notes The value for StatPct should reflect the progress of the entire translation process. 
Even if there are several discrete tasks involved in a translation, StatPct should reflect 
the total progress toward translating the file. For more information, see the previous 
section ‘Reporting the Progress of a Translation." 


If the StatMsg parameter is empty (that is, it is a string whose length is 0), Apple File 
Exchange displays the most recently displayed message. To erase the last message 
displayed, include a space character as the StatMsg parameter. 


Example Result := CallStat (MyString, 33, 1, MyData^.trnStatProc); 
displays MyString and shows that the translation is one-third finished. 


See aiso The description of the trn, File message. 
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Calls from translators to transliteration routines 


Translators can move files between different computers used in the same country. To 
do this, translators that translate text must be able to transliterate files, that is, to 
convert the characters in a file to equivalent characters in another character set. Here 
is an example: a translator is moving a file containing text from a French Apple II to a 
French Macintosh. One of the characters to be translated is the character 2. This 
character is represented by the hexadecimal number 40 on the French Apple II, while 
on the Macintosh the same character is represented by the hexadecimal number 88. 
The translator must see to it that the French Apple II representation for the 2—and for 
all the other characters in the file—is converted to the representation used by the 
Macintosh. 


About transliteration procedures and TProcs 


A transliteration procedure is any procedure that a translator uses to transliterate 
files. With Apple File Exchange and certain other applications, Apple provides 
transliteration resources known as TProcs. If a TProc for a particular transliteration is 
not available, translators must provide their own transliteration procedure. 


When designing a translator, observe the following rules: 


O If your translator translates text, use TProcs whenever appropriate. Your translator 
should be able to transliterate between any of the character sets for which there are 
TProcs. 


C Be aware that certain applications (for example, Lotus 1-2-3) use their own 
character sets. If you are designing a translator for files created by such an 
application, you must provide your own transliteration routines. 


C Keep all text strings displayed by translators in resources. The resource IDs for 
these strings should be in the same range as the resource ID for the 
translator—specifically, the range [translator-resource-ID..translator-resource-ID 
+ 24]. 


When a translator moves a file containing text to a computer, file system, or 
application with a different character set, it must transliterate the file. Transliterating a 
file converts the representation of each character in a file to the representation used in 
another character set. Apple File Exchange provides TProcs that perform 
transliterations between character sets used by computers in the same country. For 
example, on a French Macintosh there are TProcs available for transliterating text 
between a French Apple II, a French Macintosh, and a French IBM PC. Each TProc 
handles two transliterations: the transliteration from one character set to a second 
character set and the transliteration from the second character set to the first. The 
following sections explain how to use TProcs. 


When there is no TProc for a particular transliteration, such as a transliteration 
involving a special character set used by an application, translators must provide their 
own transliteration routines. 


Calls from translators to transliteration routines 
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Using the translation parameter block for file system calls 


A file system resource can be both relocated and purged, so calling it requires getting a 
handle to its current location in memory. For any translation, the translation 
parameter block contains the resource IDs for both the source and destination file 
systems; the IDs can then be used in GetResource calls to get the handles. In addition, 
file systems have global storage that they use in much the same way as translators. A 
call to a file system must include a pointer to this global storage, which is kept in the 
transiator parameter block. 


The translation parameter block also includes volume reference numbers, parent ID 
numbers, and filenames for both the source and destination files. With this 
information, translators can make any of the file system calls. 
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Structure of TProc family resources 
A TProc family contains a record of the form 


TPRF = RECORD 
LastEntry 
Reserved 


TProcs 


END; 


: integer; 
: array(1..31] of integer; 


: array(l..LastEntry] of TPRCEntry 


The fields in the TPRF record have the following meanings: 


LastEntry The number of TProcs in the family. 
Reserved. Reserved for future expansion; may contain version information in 
the future. 
TProcs An array with LastEntry elements containing information about each 
TProc in the family. The form of the entries is described below: 
CharFam : integer; 
Count ryCode : integer; 
TPRCEntry = RECORD 
tprcID : integer; 
|J curCharFam : CharFam; 
altCountry : CntryCode; 
altCharFam : CharFam 


END; 


The fields in the TPRCEntry record have the following meanings: 


tprcID 
curCharFam 


altCountry 


altCharFam 


Tbe resource ID of the TProc. 


The character set family number for the TProc's source character set. 
Character family values for Apple File Exchange TProcs are listed in 
Table 2-8. 


The country code for the destination country. This code is the same 
as the resource ID for the TProc family. For TProcs provided with 
Apple File Exchange, the source country code and destination 
country code are always the same. 

The character set family number for the TProc's destination character 
set. 
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Notes To ensure proper operation of Apple File Exchange, translators should use CallFS for 
Macintosh file system calls rather than make direct calls to the Macintosh File 
Manager. 


Example ResultCode := CallFS (FFGetVInfo, MSDOSData, 
PBHParamBlockRecPtr, FALSE, MSDOSHandle); 


calls the FFGetVInfo routine to get information about a volume. The parameter block 
is used to pass information about the volume to the routine and back to the calling 
translator. The operation is performed synchronously. 


See aiso Chapters 4 and 5 for details about each value of the Msg parameter. 


Table 2-7 
Values for the CallFS Msg parameter 


i ir ——_—_—_—— 
Constant identifier Value Constant identifier Value 
Pehle eee 


FFAllocate 19 FFOKFName 52 
FFAllocContig 20 FFOpen 9 
FFClose 22 FFOpenRF 10 
FFCloseWD 36 FFOpenWD 35 
FFCreate 23 FFRead 13 
FFDelete 25 FFRename 31 
FFDirCreate 24 FFRstFLock 29 
FFFiushFile 21 FFSetCatinfo 33 
FFFiushVol 5 FFSetEOF 18 
FFGetCatInfo 32 FFSetFInfo 27 
FFGetEOF 17 FFSetFLock 28 
FFGetFInfo 26 FFSetFPos 16 
FFGetFPos 15 FFSetFVers 30 
FFGetVInfo 1 FFSetVInfo 2 
FFGetWDinfo 37 FFUnlockRange 12 
FPLockRange 11 FFWrite 14 
FFMakeDName Sá FFXGetCatinfo 50 
FFMakeFName 47 FFXSetCatInfo 51 
FFOKDName $3 
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Translit—an example of a TProc 





A TProc transliterates the characters in a file. 


A TProc is called when the character set families for the source and destination files 
are different. 


TYPE 
CharFam = integer; (Code for character set family) 


CntryCode = integer; (Country code for TProc source or destination 


country) 
TransText * RECORD 
trPtr : ptr; 
trLen : longint; 
trFont : integer 
END; 
TransPB = RECORD 
verb : integer; 
featureFlags : integer; 
result : OSErr; 
newCntry : integer; 
srcText : TransText; 
dstText : TransText; 
tpRsrv : array [0..3] OF longint 


END; 
FUNCTION Translit (params : TransPB, Self : handle) : OSErr; 


INLINE $2057, $2050, $4E90; 
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TProcs as resources 


TProcs are kept in resources whose resource type is 'tprc'. In tum, TProcs are grouped 
into resources known as TProc families. TProc families contain all the available 
TProcs for transliterating files within the same source country. For example, ali 
TProcs for transliterating files that originated on a French version of the Macintosh, 
Apple II, or IBM PC are in one TProc family, while TProcs for files that originated on 
an Italian version of the Macintosh, Apple II, or IBM PC are in another. 


One TProc family is built into Apple File Exchange. Both the source country and 
destination country for this TProc family are the same as the country code for the 
version of the Macintosh system software with which it is included. (Country codes are 
described in the "International Utilities Package" chapter in Volume I of Inside 
Macintosh.) This means that there are TProcs for transliterating files between versions 
of the Macintosh, Apple II, and IBM PC that are designed for the same country. 
TProcs for transliterating between languages used in different countries may be 
provided with other applications, such as terminal emulators, but they are not 
included with Apple File Exchange. 


The resource type of TProc families is 'tprf*. 


The source and destination countries for TProcs provided with Apple File Exchange 
are always the same. 


The resource ID for a TProc family is the same as the country code for the Macintosh 
with which Apple File Exchange is bundled. Country codes are listed in the 
"International Utilities Package" chapter in Volume I of Inside Macintosh. When 
necessary, additional country codes will be defined by Macintosh Technical Support. 


Because TProc resources are separate from translator resources, translators cannot 
make calls to TProcs through normal Pascal calling conventions. As with Apple File 
Exchange routines, translators written in Pascal must circumvent the normal flow of 
control through the use of inline machine instructions. The MPW Pascal INLINE 
directive (or the equivalent technique in other languages) allows translators to replace 
the JSR assembly-language instruction that concludes normal MPW Pascal routines 
with other instructions, making these calls possible. 

The machine-language instructions used for TProcs are described with the sample 
TProc that follows. For information on Pascal calling conventions, see Appendix A, 
"Pascal Conventions for Translators." For information on the INLINE directive, see 
the Macintosh Programmer's Workshop Pascal Reference. 
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TProcs return an Operating System result code as the function result. If the result is 
noErr (= 0), the transliteration was performed successfully. In addition to the 
standard Macintosh result codes, the following result codes are defined for TProcs: 


tDstTooShort = -501; (Destination buffer too short} 
tSubsetSwitch = -502; {Source changed character subset} 
tPartialChar = -503; {Source ends with a partial character) 


The following parameters are also used for output: 


result Copy of the function result 

newCntry Country code for the TProc used 

secText.trPtr Pointer to the source buffer for the transliteration 
srcText.trLen | Number of bytes from the source buffer that were not translated 
dstText.trPtr Pointer to the destination buffer for the transliteration 
dstText.trLen | Number of bytes in the destination buffer that were not used 


ResultCode := Translit (MyParamBlock, MySelf); 


transliterates the buffer pointed to by MyParamBlock.srcText.trPtr and puts the result 
in the buffer pointed to by MyParamBlock.dstText.trPtr. ResultCode contains the 
result code for the function. 


The translator example in Appendix C. 
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Table 2-8 
CharFam values for Apple 
File Exchange TProcs 





Name Value 





cfMacintosh 0 
cfASCII 1* 
cfIBMPC 2 


*cfASCII is the CharFam value 
for character sets used by the 


Apple II. 


a 


Using TProcs 


These are the steps a translator must perform when using a TProc: 


L; 


Get the value of the tmCountry field from the translation parameter block. This 
Geld identifies the international version of the Macintosh on which Apple File 
Exchange is running, The value is the same as the country code for the Macintosh 
on which Apple File Exchange is running. 


. Using the GetResource routine, open the TProc family resource whose resource ID 


is the same as the country code from step 1. 


Search the table of entries in the family for the TProc with the correct curCharFam 


and altCharFam values. For example, to find the TProc for transliterating a file 
from an Apple II to a Macintosh, search for the entry where one of the two fields 
curCharFam or altCharFam contains 1 and the other field contains 0. 


. The tprcID field for the entry contains the TProc's resource ID. Use the value from 


this field to open the TProc resource. 


. Call the TProc. 
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Examples of translations 

The following examples illustrate the tasks translators perform. They show the 
relationships between 

o actions by Apple File Exchange users 

O messages sent by Apple File Exchange to a translator 

o what the translator does when it's sent a message 

For detailed information about each of the messages and about messages not included 
in the examples, see Chapter 3, "Messages From Appie File Exchange to T ranslators." 
For information on using Apple File Exchange, see the Apple File Exchange chapters 


in the Macintosh Utilities User's Guide. For the Pascal code for a sample translator, see 
Appendix C, “An Example of a Translator." 





A simple translation 
This example shows what occurs during a simple session with Apple File Exchange. 
What the user does Message sent What the transiator does 


Starts Apple File trn_Init Initializes any global variables it needs 
Exchange 


trn_Get Provides its current status (Apple File 
Exchange uses this status to determine if an 
About button should be available for the 
translator) 


Inserts disk un, Appear Learns that the menu containing its menu 
item is active; may allocate more global 
memory or change the appearance of its 
menu item 


trn, Get Provides its current status (Apple File 
Exchange gets this information before 
displaying the translator's menu item) 


Selects file No message 
to translate sent 
Presses Translate un NewName Provides a new name for the file to be 
button translated 

trn File Translates the file 
Exits Apple File un Pinis Releases any global memory it has allocated 
Exchange 


Examples of translations 
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The inline instructions are hexadecimal equivalents for the following 68000 assembly 
language instructions: 
> Take the handle to the TProc off the stack 


; and put it in register AO 

MOVE.L (A7), AO 

: Dereference the handle to get the pointer to the TProc; 
; put the pointer in register AO 

MOVE.L (A0), AO 

: Use the JSR (Jump to Subroutine) instruction to push a 
; return address on the stack and then jump to the TProc 


; pointed to by AQ 


JSR (AO) 
input The input parameters for a TProc are 
verb Indicates the operation to be performed by the TProc. It can have 


one of the following values: 


transInit = 0; {Initialize the TProc; performed before 
using TProc} 


transDone - 1; (Perform any cleanup required after 
using TProc} 


transLowToHigh = 2; {Transliterate from lower-numbered 
character set family to higher- 
numbered character set family! 


transHighToLow = 3; (Transliterate from higher-numbered 
character set family to lower- 
numbered character set family! 


featureFlags Apple File Exchange TProcs do not support any of the features 
indicated by these flags. Set this field to 0. 


newCntry For input, set this field to ~1. 
srcText.trPtr Pointer to the source buffer for the transliteration. 
srcText.trLen The length, in bytes, of the source buffer. 


srcText.trFont The font number of the font used in the source file. For Macintosh 
files, this is the font number recognized by the Font Manager. For 
Apple II and IBM PC files, this field is set to O. 


dstText.trPtr Pointer to the destination buffer for the transliteration. 
dstText.trLen The length, in bytes, of the destination buffer. 


dstText.trFont The font number of the font used in the destination file. For 
Macintosh fonts, this is the font number recognized by the Font 
Manager. The meaning of the number for other computers varies, 
but 0 typically refers to the system font, while 1 refers to the font 
used by most applications. (For some computers, dstText.trFont 
may be the same as the system font.) 


tpRsrv For input, the elements of this array must be set to 0. 
Self Handle to the TProc function. 
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Chapter 3 


Messages From 
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to Translators 
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——————— el SSSSSSS== 
Advanced topics 


The following sections present advanced topics related to translator implementation. 


ee a — € — 


Customizing icons 


You can create your own icon for a translator file by following these steps. 

1. Create the translator file. The file type for this file is 'VISA". 

2. Assign the file a unique four-byte creator type. The Finder?" will use this creator 
type to identify the icon that goes with the file. 

3. Register the creator type with Macintosh Technical Support. 

4. In the resource file containing the translator, include a version data resource whose 
resource type is the same as the creator type for the translator and whose resource 
ID is 0. 

5. Using ResEdit, create a bundle CBNDL') and put it in the resource file containing the 


translator. The owner name for the resource must be the same as the creator type 
for the translator and the owner ID must be 0. 

6. Create an icon resource CICN#') in the resource file containing the translator. This 
icon is what will be displayed in the Finder. The icon should be the same as the 
icons used for translators provided by Apple, with one exception: you must replace 
the Apple logo in the lower-right corner of the icon with a logo of your own design. 

7. In the resource file containing the translator, include file reference resources that 
link the icon and the file type 'VISA'. 

8. Set the bundle bit for the translator. 


For more information about icons, see the "Finder Interface" chapter in Volume III of 
Inside Macintosh. 


a 


Translating files in place 


Apple File Exchange allows the source file for a translation to be the same as the 
destination file. When performing such a translation, translators must create a 
temporary file for the results of the translation, then replace the original file with the 
translated version. 
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trn About—provide information about the translator 


The trn About message requests a translator to provide information about itself, 
either by displaying a dialog box or by providing text containing information about 
the translator. 


This message is sent to a translator when the user selects the About Appie File 
Exchange menu item from the Apple menu and then selects the translator in the 
dialog box that appears. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


unFrData Pointer to global data for the source file system 
trnFrID Resource ID for the source file system 

trnLogProc Pointer to the User Log procedure 

unToData Pointer to global data for the destination file system 
unToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


The translator can return one of three function results: 


O The value 0 if the translator displays its own dialog box that includes information 
about the translator. 

O The resource ID for a resource of type 'TEXT'. This resource, which contains 
information about the translator, must contain only printable ASCII characters 
and carriage returns. 


O A negative number (usually an error code) if no About information is available. 


Apple File Exchange displays text from a 'TEXT' resource in a TextEdit window that 
includes a vertical scroll bar and a close box. To enable the text to fit within the 
window, it breaks lines at word boundaries where necessary. 

An About 'TEXT' resource consists of a string of printable characters with carriage 
returns to separate paragraphs. The maximum size of an About 'TEXT' resource is 
32K. 


trn About 3-3 


er pt UU UU ERR E —Á———————— 


A canceled transiation 


In this example, no file is actually translated. The example demonstrates some of the 
features that give Apple File Exchange its flexibility. 


What the user does 


Starts Apple File 
Exchange 


Inserts disk 


Selects Eligible 
File command 


Deselects 
a translator 


Selects files 


Deselects Eligible 
File command 


Selects Rename 
Dest. Files 
command 


Renames 
destination files, 
clicks Cancel box 
Ejects disk 
containing 

the Apple File 
Exchange 


Selects 
About AFE 
command 


. Exits Apple File 
Exchange 
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Message sent 


un. Init 

trn, Get 

Hn. Appeir 
trn, Get 

un, Recognize 
trn. Deactivate 
trn Recognize 


No message 
sent 


No message 
sent 


trn, NewName 


No message 
sent 


trn, Load 


trn, About 


urn Finis 


What the transiator does 
Initializes any global variables it needs 


Provides its current status (Apple File 
Exchange uses this status to determine if an 
About button should be available for the 
translator) 


Learns that the menu containing it is active; 
may allocate more global memory or change 
the appearance of its menu item 


Provides its current status (Apple File 
Exchange gets this information before 
displaying the translator’s menu item) 


Determines if it can translate the file (a 
un, Recognize message is sent for each file 
in the current directory) 


This message is sent only to the translator 
that was deselected; if this is the translator, 
then it updates its status 

If its menu item appears below the menu item 
for the translator that was deselected, it 
determines again if it can translate a file 


Provides a new name for a file to be 
translated 


Loads any resources from disk that it needs 
(this makes it less likely that the user will 
have to reinsert the disk) 


Provides a dialog box that describes the 
translator or returns the ID of a text resource 
containing a description of the translator 
(in the latter case, Apple File Exchange 
opens the text resource and displays it in a 
dialog box) 


Releases any global memory it has allocated 
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trn Appear—respond to menu appearance 


The trn Appear message informs a translator that a menu containing its menu item 
will appear in the menu bar. The translator can then determine the file systems for the 
new menu and perform any actions, such as changing the appearance of its menu 
item or allocating more memory, that are necessary. 


The trn Appear message is sent when 

C the user selects a new source or destination disk in either of Apple File Exchange's 
file windows 

OQ a translator is imported to a new menu 


Apple File Exchange passes a pointer to the translation parameter block in the Param 
parameter. For this message, the translation parameter biock includes these values: 


trnFrData Pointer to global data for the source file system 
trnFriD Resource ID for the source file system 
trnFrVRef Volume reference for the source disk 


trnLogProc Pointer to the User Log procedure 

trnToData Pointer to global data for the destination file system 
trnToID Resource ID for the destination file system 
trnToVRef Volume reference for the destination disk 


All other values in the translation parameter block for this message are undefined. 


The translator returns the function result 0 if the operation was successful or an error 
code (usually for a memory allocation or file system error) if it was not 


Upon receiving the trn_Appear message, a translator can get information about the 
source and destination volumes and determine if the appearance of its menu item 
needs to change. For example, a translator may need to change its menu item's 
appearance if it is imported to another menu. After sending the trn_Appear 
message, Apple File Exchange sends a trn_Get message and updates the appearance 
of the translators menu item before displaying the new menu. 


It is possible for one disk to be both the source and destination for a translation. If the 
trnFrID and trnToID fields match and the trnFrVRef and trnToVRef fields match, the 
source and destination disks are the same. 


When a translator receives the turn Appear message, it can also allocate global 
memory it needs before being activated. As discussed in the description of the 

trn. [Init message, translators that use large amounts of global data can help to 
conserve memory by deferring memory allocation until they receive a trn Activate, 
trn, Appear, or urn, File message, depending on the memory needs of the 
translator. In doing so, the translators avoid allocating memory before they actuaily 
use it 


If a translator returns an error code as the function result, Apple File Exchange sends a 
un, Set message to set the Gray flag and clear the Active flag in the translator's status. 
This unchecks the translators menu item and makes it appear gray in the menu. 
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This chapter provides detailed reference information about the messages sent to 
translators by Apple File Exchange. Table 3-1 lists the messages sent to translators and 
summarizes the actions that translators must perform in response to the messages. 
Following the table are descriptions of each of the messages. 


Table 3-1 


Messages sent to translators 


Message 


un, About 
trn, Activate 


trn, Appear 


trn. Deactivate 


trn, Disappear 


un, File 

trn, Finis 
trn, Get 

un, GetSettings 
trn, Init 

un Load 
trn_NewName 
trn_Recognize 
trn_Set 


trn_SetSettings 
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What transiator must do 


Provide information about the translator 
Activate (check) the menu item for the translator 


Perform any actions necessary (such as changing the appearance 
of the menu item) when a menu containing the translator appears 


Deactivate (uncheck) the menu item for the translator 


Perform any actions (such as freeing memory) needed when a 
menu containing the translator's menu item disappears 


Translate a file 

Perform any cleanup needed before exiting 
Return current status of the translator 

Get the current settings for the translator 
Initialize the translator 

Load resources used by the translator 

Return a new name for a file 

Determine if the translator can translate a file 
Set status of the translator 

Set the settings for the translator 
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Description 


When sent 


Input 


Notes 


See also 








trn_Deactivate—deactivate the translator 


The trn, Deactivate message informs a translator that its menu item is no longer 
active and requests an updated translator status. 


This message is sent when the user, without holding down the Option key, selects a 
translator whose menu item is checked. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData Pointer to global data for the source file system 
trnFrID Resource ID for the source file system 

trnLogProc Pointer to the User Log procedure 

unToData Pointer to global data for the destination file system 
tn ToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 
The translator updates its status flags and returns them as the function result. 


For many translators, the only action required in response to a un, Deactivate 
message is to clear the Active flag in their status flags and return the new status as the 
function result. Note, however, that translators are not required to clear the Active 
flag in response to this message. For example, a translator that must always be active 
would never clear the Active flag. 


Only the trn, Activate message is sent when a default translator is chosen; no 
un, Deactivate message is ever sent for a default translator. 


trn, Activate. 
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Description 


When sent 


Input 


Notes 


See also 
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trn_Activate—activate the translator 


The trn_Activate message informs a translator of events involving the menu item for 
the translator (see “When sent" below) and requests an updated translator status. 


The trn. Activate message is sent when a user 
Oo selects an inactive translator from a menu 


o holds down the Option key while selecting an available menu item (that is, a menu 
item that is not gray) 


In the second case, the trn Activate message is sent whether or not the translator is 
active. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData Pointer to global data for the source file system 
unFrID Resource ID for the source file system 

trnLogProc Pointer to the User Log procedure 

trnToData Pointer to global data for the destination file system 
trnToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 
The translator updates its status flags and returns them as the function result. 


For many translators, the only action required in response to a un, Activate message 
is to set the Active flag in their status flags and return the new status as the function 
result. Note, however, that translators are not required to set the Active flag in 
response to this message. For example, some translators display a dialog box when 
their menu item is selected. If a user deactivates the translator by clicking the Cancel 
button in the dialog box, the translator would not set the Active flag. 


When it receives the trn Activate message, a translator can also allocate any global 
memory it needs before being activated. As discussed in the description of the 

trn, Init message, translators that use large amounts of global data can help to 
conserve memory by deferring memory allocation until they receive a trn_Activate, 
trn. Appear, or un, File message, depending on the memory needs of the 
translator. In doing so, the translators avoid allocating memory before they actually 
use it. 

A trn. Activate message is sent whenever a default translator is chosen, but no 

un, Deactivate message is ever sent for a default translator. 


trn_Deactivate and tun Init. 
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Description 


When sent 


Input 


trn. File—translate a file 


The trn File message requests a translator to convert a file and move it to its new 
destination. 


The trn. File message is sent when the user clicks the Translate button in the Apple File 
Exchange window or in the Rename dialog box. 


Apple File Exchange passes a pointer to the translation parameter block in the Param 
parameter. For this message, the translation parameter block includes these values: 


trnAccepted If the trn Tested field is TRUE, indicates whether a file was accepted 
for translation 


trnCountry Country code for the version of the Macintosh on which Apple File 
Exchange is running 


unFrData Pointer to global data for the source file system 

trnFrID Resource ID for the source file system 

trnFrPar Parent ID of the directory containing the file to be translated 
trnFrVRef Volume reference for the source disk 


trnLogProc Pointer to the User Log procedure 

trnNames^^.nameCnt 
Number of destination files for the translation. (In the current 
release of Apple File Exchange, this field always contains one.) 


trnNamesAA.names(0] 
Name of the file to be translated 


trnNamesAA.names(1] 
Name of the destination file for the translation 


trnStatProc Pointer to the Status procedure 


trnTested Indicates whether the translator has already been sent a 
trn Recognize message for a file; if the value of trnTested is TRUE, 
the translator does not have to determine again if it can translate the 


file 

unToData Pointer to global data for the destination file system 

unToID Resource ID for the destination file system 

trnToPar Parent ID of the directory where the file to be translated will be 
copied 

trnToVRef Volume reference for the destination disk 


The translator must return one of these function results: 


o Accept (= 0) if the translator accepted the file and either translated the file or could 
not translate the file for a reason outside its control (see "Notes" below) 


OQ Unaccept (= 1) if it did not accept the file or discovered that it was not able to 
translate the file 


O TrnCancel (= 2) if the translator called the CallStatus function while translating (see 
*Notes" below) and received FALSE as a result 
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For each trn, Appear message, there is not always a matching turn, Disappear 

message. For example, a user clicking the Drive button in the Apple File Exchange 

window can switch to a second disk whose file system is the same as the first. This is 

what happens: 

à Because the source and destination file systems remain the same, the translator 
menu(s) remain unchanged, and no un Disappear message is sent. 

C Because the user has selected a new source or destination disk, a trn Appear 
message is sent. 


See aiso trn Activate, urn, Disappear, un Get, and trn Init. 
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Description 


When sent 


Input 


Notes 











trn_Finis—perform cleanup on exit 


The trn_Finis message requests a translator to dispose of any global memory it has 
allocated. 


This message is sent when the user 

Q removes the translators menu item from a menu 

O quits Apple File Exchange 

Future versions of Apple File Exchange may also send the message at other times. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


unFrData Pointer to global data for the source file system 
trnFrID Resource ID for the source file system 

unLogProc Pointer to the User Log procedure 

trnToData Pointer to global data for the destination file system 
trnToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 
None. 


The trn Finis message is never sent to a translator if the translator's initialization 
failed. 
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trn_Disappear—respond to disappearance of menu 


Description The un, Disappear message informs a translator that a menu containing its menu 
item has disappeared from the menu bar. 


When sent The trn_Disappear message is sent when the user selects a different source or 
destination disk and, in so doing, changes the source or destination file system. 


input The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block indudes these values: 
trnFrData Pointer to global data for the source file system 
trnFrID Resource ID for the source file system 
trnLogProc Pointer to the User Log procedure 
unToData Pointer to global data for the destination file system 
trnToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


Output None. 


Notes When translators receive the tm_Disappear message, they may choose to dispose of 
any global memory they allocated during a translation or when they appeared. 


See also trn_Appear. 
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Description 


When sent 


input 


Notes 


See also 











trn_GetSettings—provide current settings 


The trn. GetSettings message requests a handle to the current settings for a translator. 


This message is sent when the user selects the Save Settings As menu item from the File 
menu. 


None. 


A translator with settings must return a handle to its settings as the function result. 
Translators that have no settings must return 0 as the function result. 


Some translators provide a dialog box that allows users to specify one or more 
translator settings. By choosing the Save Settings As dialog box, users can save these 
settings in Apple File Exchange documents. Saved settings take effect when an 
Apple File Exchange document is opened or when a user chooses the Restore Settings 
From menu item and selects a file containing settings. The trn, GetSettings message 
requests the current settings for a translator. 


To save any settings necessary, a translator can call the NewHandle routine to create a 
block of the appropriate size and put the data in the block that is created. Apple File 
Exchange disposes of the handle that is passed to it; a translator must not dispose of 
it. 

There are no requirements for the settings a translator saves. Moreover, not all 
translators have settings. Translators that have no settings must return O as the 
function result. 

Apple File Exchange saves the status flags for each translator with the translator's 
settings. 


trn_SetSettings. 
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Notes 


See aiso 
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The trn, File message is only sent to translators whose Active status flag is set. 


To determine if it accepts a file, the translator must use the same algorithm it uses 
when sent the trn. Recognize message. A translator can often save a step by looking at 
the tnTested and unAccepted fields in the translation parameter block: 


o The tnTested field is TRUE if the translator has already tried to recognize the file. 


o If the value of the trnTested field is TRUE, the trnAccepted field indicates whether 
the translator accepted the file. 


There are no restrictions on the way a translator converts a file or moves the file to its 
destination. 


As it translates a file, a translator must periodically call the CallStatus function to 
inform the user of its progress. This procedure, described in Chapter 2 in the section 
“Calls From Translators to Apple File Exchange," accepts as input both a string 
containing information about the translation and a percent-complete value for the 
translation. If CallStatus returns FALSE, the user has canceled the translation. If this 
happens, the translator must close and delete any files it has created and return 
TrnCancel (= 2) as the function result. 


If an error occurs while translating a file, the translator must inform the user by calling 
the CallLog or CallErrLog procedure. These procedures are described in Chapter 2 in 
the section "Calls From Translators to Apple File Exchange." 


In the event that an error outside the control of the translator (such as a disk error) 
prevents a file from being translated, the translator should return Accept. Because the 
same error will likely prevent other translators from translating the file, returning 
Accept keeps other translators from attempting the translation. 


If 2 translator discovers it cannot translate a file because it recognized the wrong file, 
or because of an error in the translator itself, it should return Unaccept and put an 
entry in the User Log. When, in the current version of Apple File Exchange, a 
translator returns Accept or Unaccept, no other translator will attempt the 
translation. 


When it receives the trn. File message, a translator can allocate any global memory it 
needs before translating a file. As discussed in the description of the trn Init 
message, translators that use large amounts of global data can help to conserve 
memory by deferring memory allocation until they receive a trn, Activate, 

trn Appear, or un, File message, depending on the memory needs of the 

translator. In doing so, the translators avoid allocating memory before they actually 
use it. 


un, Recognize. 


trn. File 


Notes 


See also 


If initialization of a translator is not successful, the translator must put an error 
message in the User Log in addition to returning an error code. 


Translators that use large amounts of global data can help to conserve memory by 
deferring memory allocation until they receive a trn, Activate, trn Appear, or 
tm, File message, depending on the memory needs of the translator. In doing so, 
translators avoid allocating memory before they actually need it 


Apple File Exchange keeps separate copies of TranslateData for translators that are 

imported to other menus. This means that translators that appear in more than one 
menu are treated like separate translators. For these translators to respond properly 
to a message, they need only use the TranslateData value supplied with the message. 


Translators should normally work in any menu to which they are imported. 5ome 
translators, however, may not work properly when imported. Such translators can do 
the following to see what menu they are being moved to: 


o Call GetResource to get handles to the source and destination file systems. 

O Using the handles, call GetResInfo to get the resource name for each file system. 

J Look at the last two characters in each resource name. These characters identify the 
file system. 


if a translator will not work if imported to the new menu, it should notify the user by 
displaying an alert box. In addition, the translator can return an error code to 
prevent its menu item from being displayed. 


trn Appear. 
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trn_Get—return current status of translator 
Description The trn, Get message is sent to obtain the current status of a translator. 
When sent This message is sent after each trn Appear and trn Init message. 
input None. 


Output The translator returns its status flags as the function result. For descriptions of the 
status flags, see “The TranslateData Parameter” section in Chapter 2. 
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Description 


When sent 


input 











im_NewName—give file a new name 
The un NewName message requests a new name for a file. 


The tn_NewName message is sent 
Q before Apple File Exchange transiates a file 
o when a file is renamed 


Apple File Exchange passes a pointer to the translation parameter block in the Param 

parameter. For this message, the translation parameter block includes these values: 

unAccepted Ifthe trnTested field is TRUE, indicates whether a file was accepted 
for translation 


unFrData Pointer to global data for the source file system 

trnFriD Resource ID for the source file system 

trnFrPar Parent ID of the directory containing the file to be translated 
trnFrVRef Volume reference for the source disk 


trnLogProc Pointer to the User Log procedure 


trnNames^^.namesio] 
Name of the file to be translated 


trnNames^^.nameCnt 
The value 1, which is the number of destination files created. 
Because the current version of Apple File Exchange can only create 
a single destination file, do not change this value 


trnTested Indicates whether the translator has already been sent a 
un Recognize message for a file; if the value of trnTested is TRUE, 
the translator does not have to determine again if it can translate the 


file 

trnToData Pointer to global data for the destination file system 

trnToID Resource ID for the destination file system 

trnToPar Parent ID of the directory where the file to be translated will be 
copied 

ttrnToVRef Volume reference for the destination disk 


All other values in the translation parameter block for this message are undefined. 


The translator must return one of two function results: 
D Accept (= 0) if the translator recognized the file to be translated 
D Unaccept (= 1) if it did not recognize the file to be translated 


If the translator accepts the file, it must also return a new name for the destinauon file. 
The new name is returned in the field trnNames^^.namesí1]. 
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Description 


When sent 


Input 











trn Init—initialize the translator 
The trn, Init message requests a translator to initialize any variables that it uses. 


The trn Init message is sent when 
o Apple File Exchange is opened 
C the translator is imported to another menu 


C the menu item for a translator that has been removed from its original menu is 
returned to the menu 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData Pointer to global data for the source file system 
trnFrID Resource ID for the source (ile system 

unLogProc Pointer to the User Log procedure 

trnToData Pointer to globai data for the destination file system 
trnToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


The translator returns one of two values in the TranslateData parameter: 


© If the translator needs no more than four bytes of global data, it can store the data 
in the TranslateData parameter. Most translators use the TranslateData parameter 
to store the default value for the translator status. 


C) If a translator requires more than four bytes of global data, it can allocate some 
relocatable memory and store a handle to it in TranslateData. 


Apple File Exchange passes the value stored in TranslateData back to the translator 
with each subsequent message. 

The translator must also return a function result: 

O The value 0 if the translator was initialized successfully. 


O An error code (typically a memory allocation error) if the initialization was not 
successful. If a translator returns an error code, its menu item is not displayed. 
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Description 


When sent 


input 


Notes 








tm_Recognize—determine if file can be translated 


The trn, Recognize message requests an active translator to examine a file and to 
determine if it can translate the file. 


This message is sent when the Show Only Eligible Files menu item 
C is selected 

O is checked and a translator is activated or deactivated 

o is checked and the user opens another directory 


The Param parameter contains a pointer to the translation parameter block. The 
parameter block includes these values: 


trnAccepted If the trn Tested field is TRUE, indicates that the translator receiving 
the trn, Recognize message has already recognized the file 


trnFrData Pointer to global data for the source file system 

trnFrID Resource ID for the source file system 

unFrPar Parent ID of the directory containing the file to be translated 
trnFrVRef Volume reference for the disk containing the file to be translated 


trnLogProc Pointer to the User Log procedure 

trnNames^^.nameslO] 
Name of the file to be translated 

trnTested Indicates whether the translator has already been sent a 
trn_Recognize message for a file. Normally FALSE; if TRUE, the 
translator does not have to determine again if it can translate the file 


For this message, ali other fields in the translation parameter block are undefined. 


The translator must return one of two function results: 
o Accept (= 0) if the translator recognized the file to be translated 
C Unaccept (= 1) if it did not recognize the file to be translated 


The trn. Recognize message is only sent to translators whose Active status flag is set. 


If more than one special-purpose translator (that is, a translator whose resource ID is 
greater than 2000) recognizes a file, Apple File Exchange displays a dialog box that 
allows the user to select which translator to use. This dialog box appears after the user 
has selected the file(s) to translate and then selects the Translate button. If only one 
special-purpose translator recognizes a file, that translator is used to translate the file. 
If only general-purpose translators (those with resource IDs less than or equal to 2000) 
recognize a file, the translator with the highest resource ID is used to translate the file. 


The criteria a translator uses to recognize a file depend on the nature of the 
translation. See the section "Recognizing Files" in Chapter 2 for information about 
choosing recognition criteria. 
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trn_Load—load resources 


Description The trn_Load message requests a translator to load any resources it needs from the 
disk containing Apple File Exchange. 


When sent This message is sent to active translators when the user ejects the disk containing 
Apple File Exchange. This can occur often when users have only one or two disk 


drives. 
Input The Param parameter contains a pointer to the transiation parameter biock. For this 
message, the parameter block includes these values: 
unFrData Pointer to global data for the source file system 
trnFrID Resource ID for the source file system 
trnLogProc Pointer to the User Log procedure 
trnToData Pointer to global data for the destination file system 
trnToID Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


Output None. 


Notes By loading resources it needs before a user ejects the Apple File Exchange disk, a 
translator can help users avoid swapping disks. 


3-16 trn_Load 


Description 


When sent — 


Input 


Notes 


See also 


trn_SetSettings—set translator settings 
The trn_SetSettings message provides a handle to a new set of translator settings. 


The trn_SetSettings message is sent when the user selects the Restore Settings From 
item from the File menu. 


A handle to the translator's new settings is passed in the Param field of the translation 
parameter block. 


None. 


Some translators provide a dialog box that allows users to specify one or more 
translator settings. By choosing the Save Settings As dialog box, users can save these 
settings in Apple File Exchange documents. Saved settings take effect when an Apple 
File Exchange document is opened or when & user chooses the Restore Settings From 
menu item and selects a file containing settings. 


The un SetSettings message provides the translator a handle to saved settings. The 
translator can then update its own internal copy of the settings and refer to them when 
it translates files. Apple File Exchange disposes of the handle it passes; a translator 
must not dispose of it. 

Apple File Exchange saves the status flags for each translator with the translator's 
settings. After sending a trn. SetSettings message, Apple File Exchange issues a 

trn Set message to restore the saved status flags. 


un GetSettings. 
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Notes 


See also 
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The trn_NewName message is only sent to translators whose Active status flag is set 


To determine if it accepts a file, the translator must use the same algorithm it uses 
when sent the trn. Recognize message. A translator can often save a step by looking at 
the trnTested and trnAccepted fields in the translation parameter block: 


d The tmTested field is TRUE if the translator has already tried to recognize the file. 


o If the value of the unTested field is TRUE, the trnAccepted field indicates whether 
the translator accepted the file. 


When it accepts the file, the translator has the responsibility for selecting a new name 
for a file: 


o It can select a new name itself. 

o It can let the new file system provide an appropriate name by calling the file 
system's FFMakeFName routine. (File system routines are described in Chapter 2 in 
the section *Calls From Translators to File Systems" and in Chapters 4 and 5). 


Translators must not interrupt the user to ask for a new name. It is up to the translator, 
not the user, to suggest a new name. Afterward, the user can replace the suggested 
name with a different one. 


Translators must also check to see if a new name is an appropriate one for the new file 
system. They can do this by calling the new file system's FFOKFName routine. 


When translating files whose source and destination file system is the same, a 
translator can receive the trn. NewName message. This can occur when the source 
and destination files are of entirely different types (for example, a database file being 
translated to a text file), and the new file requires a different name or file extension. 


Users have the final say in selecting new filenames. Apple File Exchange gives them an 


opportunity to change the names that are suggested, and they may change names to 
suit their needs or to avoid conflicts with existing names. 


turn, Recognize. 


trn_NewName 
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trn_Set—set status of translator 
Description The trn Set message is sent to change the translator's status flags. 


When sent In the current version of Apple File Exchange, the trn Set message is sent 
G to set the Active flag for default translators (those with a resource ID of 0) 


O to clear the Active flag and set the Gray flag for translators that return an error 
message in response to a trn Appear message 

O to set the transiator’s status flags after a user selects the Restore Settings From menu 
item 


Input The Param parameter contains the new status flags for the translator. For descriptions 
of the status flags, see “The TranslateData Parameter” section in Chapter 2. 


Output None. 
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Limitations of the ProDOS file system 


The ProDOS foreign file system has a number of limitations that apply to all cails: 


CQ Working directories are not implemented in any form. All volume reference 
numbers must refer to actual volumes, not directories within volumes. 


G Partial pathnames are not supported. The ProDOS file system recognizes only 
volume names and filenames. 


A maximum of eight files may be open at any one time. 

ProDOS operations are always performed synchronously. The IoCompletion fieid 
of the parameter block is always ignored. The Async parameter in file system calls is 
also ignored. | 

The root directory of every volume has a directory ID of 2. 

All calls support filenames, but not pathnames. For example, 

HD:MyFolder:MyFile cannot be passed as a parameter to a ProDOS file system 
routine, but MyFile can. 

As with all Apple File Exchange file systems, the HFS version of each call is the one 


that is implemented. You must pass pointers to PBHParamBlockRec records where 
^ appropriate and include values in all the fields that are necessary for each call. 


oO O 


0 oO 


o 


File system calls not supported by the ProDOS file system 


Table 2-7 in Chapter 2 lists all the available file system calls and the corresponding 
Msg value for each call. Table 41 lists those calls that are not supported by the 
ProDOS file system. 


Table 4-1 


File system calis not supported 
by the ProDOS flle system 


Name of call Msg value 
FFAllocate 
FFAllocContig 
FFCloseWD 
FFGetWDInfo 
FFLockRange 
FFOpenRF 10 
FFOpenWD 
FFRstFLock 
FFSetFLock 
FFSetFVers 
FFSetVInfo 
FFUniockRange 


*Note that you can lock and uniock 
files by using the FFSetCaunfo call. 


Limitations of the ProDOS file system 
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FFGetCatinfo 
For the FFGetCatinfo call, the following fields return the value 0 for files: 


o 


0000 0 o 


ioFlFndrInfo 
a fdLocation 
OQ fdFidr 
ioFIStBIk 
ioFIRSLtBlk 
ioFIXFndrInfo 
ioFIRLgLen 
ioFIRPyLen 
ioFIBkDat 


The following fields return values other than 0 for files: 


a 


ioNamePtr—if the file is specified by ioFDirIndex 


o ioFRefNumber—if the file is open, this is the file reference number 


QoanaouooZdl a0 


m 


ioFlAttrib—file attributes; reflects the ProDOS access bits: 
a $01—if the file is locked 

OQ All other bits are cleared. 

ioFlFndrInfo 


o fdtype—a four-byte string that reflects the ProDOS file type. The string contains 
the ASCII equivalents for the two hexadecima! digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be 'FC  '. There is one exception: the fdtype field 
for a TXT ($04) file is 'TEXT'. 


DO fdcreator—'pdos' 

o fdFlags—All bits are cleared. 
ioDirID—file number 
ioFlILgLen—data fork logical length 
ioFIPyLen—data fork physical length 
ioFlCrDat—creation date 
ioFIMdDat—modification date 


ioFIParID—ID of parent of specified file (2 indicates that the parent is the root; 0 
indicates that the file is already at the root) 


ioFIClpSiz—512 


The following fields return the value 0 for directories: 


g 


0000 


ioFRefNum 
ioDrUsrWds 
ioDrFndrinfo 
ioDrBkDat 
ioFlAttrib 
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This chapter describes the ProDOS foreign file system provided by Apple File 
Exchange. It includes 


1 an overview of the ProDOS file system and the interface that Apple File Exchange 
provides to ProDOS 


C a list of the limitations of the ProDOS file system 


o details of the ways in which the operations provided by the ProDOS file system 
differ from the corresponding Macintosh Hierarchical File System CHFS) calls 


To use the ProDOS foreign file system, you must be familiar with ProDOS file 
operations and with the Macintosh HFS calls. For information about ProDOS, see the 
ProDOS Technical Reference Manual. For information about HFS, see "The File 
Manager” chapter in Volume IV of Inside Macintosh. 


L———— ————À———À ——————— ————M——H— 


About the ProDOS file system 


ProDOS is the Professional Disk Operating System used on the Appie II family of 
computers. ProDOS provides a hierarchical, tree-structured file system that is similar 
in many ways to the Macintosh HFS. 


Translators should never try to read ProDOS disk structures directly. Instead, they 
must use the ProDOS foreign file system resource provided by Apple File Exchange. 
There are two important reasons for using this resource: 


1. Apple File Exchange can properly handle disk swapping and other events. 

2. Translators use a single function, CallFS, to perform any of the operations provided 
by the file system. The operation performed is determined by the value of the 
CallFS Msg parameter. 


Translators also use the CaliFS function to call the other file systems supported by 
Apple File Exchange. The calls provided by CallFS are modeled after Macintosh HFS 
calls and are the same for all füe systems. Because there are important differences 
between the ProDOS and HFS file systems, the results of many ProDOS calls are 
different from the corresponding HFS calls. When there are differences, the 
differences are explained in the next section and in the descriptions of the calls. 
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FFGetFinfo 
For the FFGetFInfo call, the following fields return the value 0: 


a 


Oo o oO ü 


ioFlFndrinfo 
o fdLocation 
a fdFidr 
ioFIStBIk 

ioF IRStBik 
ioFIRLgLen 
ioFIRPyLen 


The following fields return values other than 0: 
o ioNamePtr—if the file is specified by ioFDirIndex 


a a0 n p 


ioFRefNumber—if the file is open, file reference number 
ioFlAttrib—file attributes; reflects the ProDOS access bits: 
o $01—if the file is locked 

o All other bits are cleared. 

ioFlFndrinfo 


C fdtype—a four-byte string that reflects ProDOS file type. The string contains the 
ASCII equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be 'FC — '. There is one exception: the fdtype field 
for a ‘TXT’ ($04) file is ' TEXT '. 


o fdcreator—'pdos' 

OQ fdFlags—all bits are cleared 
ioDirID—file number 
ioFiLgLen—data fork logical length 
ioFIPyLen—data fork physical length 
ioFiCrDat—creation date 
ioFlIMdDat—modification date 





FFGetFPos 
The FFGetFPos call behaves like the corresponding Macintosh call. 





FFGeiVInfo 
The FFGetVInfo call returns one of the following as the function result: 


g 
m) 


- 


If the value passed in the ioVolIndex field is greater than 0, the call returns an error. 


If the value passed in the ioVolIndex field is equal to 0, the call returns information 
about the volume specified by ioVRefNum. 


If the value passed in the ioVolIndex field is less than 0, the call uses ioNamePtr and 
ioVRefNum in the standard way. 
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ProDOS file system calls 


The following sections describe the differences between ProDOS foreign file system 
calls and the corresponding Macintosh HFS calls. 


a a e 


FFClose 
The FFClose call behaves like the corresponding Macintosh cail. 


a e 


FFCreate 


The FFCreate call creates a binary file (ProDOS file type $06). To set another type, you 
must issue a FFSetFInfo or FFSetCatInfo call. To set the auxiliary file type and access 
bits for the file, use the FFXSetCatInfo call. 


If the name of the file created does not conform to ProDOS conventions, the FFCreate 
call will fail and return the error “Bad filename." 


FFCreate may fail with the error ~9 if the file’s full pathname is greater than the ProDOS 
limit of 64 characters. 


err 


FFDelete 
The FFDelete call behaves like the corresponding Macintosh call. 
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FFDirCreate 
The FFDirCreate call behaves like the corresponding Macintosh call. 


If the name of the directory created does not conform to ProDOS conventions, the 
FFDirCreate call will fail and return the error “Bad filename." 


FFDirCreate may fail with the error “Bad filename" if the directory's full pathname is 
greater than the ProDOS limit of 64 characters. 


© Note: Translators should only use FFDirCreate to create temporary directories 
during a translation. If a translator does create a directory, it must delete the 
directory before finishing the translation. 


NENNEN MEM n n 


FFFlushFile 
The FFFlushFile call behaves like the corresponding Macintosh call. 
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FFFlush Vol 
The FFFlushVol call behaves like the corresponding Macintosh call. 
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FFMakeFName 

The FFMakeFName call accepts the following fields as input: 

o ioNamePu—a pointer to a filename 

J ioVRefNum—the volume reference number for the volume containing the file 
o ioFIParID—ID of the specified file's parent 


The FFMakeFName call converts the name pointed to by ioNamePtr into a legal 
ProDOS filename. 


This call does not check to see if the filename already exists. 





FFOKDName 


The FFOKDName call accepts the following fields as input 

o ioNamePu—a pointer to a directory name 

o ioVRefNum—the volume reference number for the volume containing the directory 
o ioFIParID—ID of the specified directory's parent 

The FFOKDName call returns noErr if the uS x ca 

. ProDOS directory name. 


This call does not check to see if the directory name already exists. 





FFOKFName 

The FFOKFName call accepts the following fields as input: 

o ioNamePtr—a pointer to a filename 

o ioVRefNum—the volume reference number for the volume containing the file 
OQ ioFIParID—ID of the specified file's parent 


The call returns noErr if the name pointed to by ioNamePtr is a legal ProDOS 
filename. 


This call does not check to see if the filename already exists. 





FFOpen 


The FFOpen call behaves like the corresponding Macintosh call, with one exception: 
the ioPermssn field must always be 0. 





FFRead 
The FFRead call behaves like the corresponding Macintosh call. 
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The following fields return values other than 0 for directories: 


60000 0 0 


ioNamePtr—if directory is specified by ioFDirindex 
ioDrDirID—directory ID (root is indicated by 2) 
ioDrNmFls— number of files and directories in this directory 
ioDriCrDat—creation date 

ioDrMdDat—same as creation date 


ioDrParID—ID of parent of specified file (2 indicates that the parent is the root; 0 
indicates that the file is already at the root) 


The PBGetCatInfo function is powerful, but it may be difficult to understand. Here is a 
summary of what it does: 


o 


ioFDirindex = n (> 0) 
INPUT 
D ioNamePtr-—ignored for input 


o ioDir[D—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirID 
for directory ! 


OUTPUT 

o ioNamePtrA—returns name of mh file or directory 

9 ioDirID—returns file number (GoFlNum) or directory number CioDrDirID) 

o ioFIParID-—returns directory number of parent of mh file or directory 

ioFDirindex = 0 

INPUT 

o ioNamePtr^—contains name of file in question (error if ioNamePtr = NIL) 

o ioDirID—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirID 
for directory 

OUTPUT 

o ioNamePtr^—unchanged 

d ioDirID-—returns file number GoFINum) or directory number (ioDrDirID) 

o ioFlParID—returns directory number of parent of file or directory in question 

ioFDirIndex = -1 

INPUT 

o ioNamePtr—ignored 


o ioDirID—if 0, use ioVRefNum for volume and directory, otherwise, use ioDirID 
for directory 


OUTPUT 
C ioNamePtrA—returns name of directory specified by ioVRefNum and ioDirID 


o ioDir[D—xreturns number of directory (ioDrDirID) specified by ioVRefNum and 
ioDirID 


D ioFlPar[D—returns directory number of parent of directory in question 





FFGetEOF 
The FFGetEOF call behaves like the corresponding Macintosh call. 
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FFSetFinfo 


For the FFSetFInfo call, the following fields are ignored: 
o ioFlFndrinfo 

O fdLocation 

o fdFldr 


The following fields may be set: 
DO ioFIFndrInfo 
o fdtype—a four-byte string that reflects ProDOS file type. The string contains the 

ASCII equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be 'FC '. There is one exception: the fdtype field 
for a TXT ($04) file is ' TEXT''. If the fdtype string does not follow this 
convention, the file type is not changed. 

o ioFlCrDat—creation date 





FFSetFPos 
The FFSetFPos call behaves like the corresponding Macintosh call. 





FFWrite 


The FFWrite call behaves like the corresponding Macintosh call. To greatly increase 
the efficiency of this call, write in 512-byte blocks. 
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The following fields return 0: 

ioAllocPtr 

io VNxtCNID 

ioVFSID 

ioVSeqNum 

ioVWrCnt 

ioVFndrinfo 

ioVAtrb 

ioVNmFls 

ioVBitMap 

ioAIBISt 

ioVSigWord 

ioVDrvinfor 

ioVDRefNum 

ioVFilCnt 

ioVDirCnt 

The following fields return information: 

o ioNamePtr—if ioVRefNum is used to specify a volume, returns name of volume 
specified 

o ioVRefNum—if ioNamePtr or drive number is used to specify a volume, returns 
reference number of volume 


o ioVCrDate—volume creation date 


ioVLsMod-—same as the volume creation date, or the volume creation date * 1 if 
the ProDOS access bit indicates that the volume has been changed 


ioVNmAIBlks—aumber of allocation blocks 
ioVAIBIkSiz—512 

ioVClpSiz—512 

ioVFrBlk—number of unused allocation blocks 
ioVBkUp—same as creation date 


bBoaooaoaqoadroaodaadadnk™dad UO 
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FFMakeDName 


The FFMakeDName call accepts the following fields from a HParamBlockRec record as 
input: 

C ioNamePtr—a pointer to a directory name 

BG ioVRefNum—the volume reference number for the volume containing the directory 
o ioFIParID—ID of the specified directory's parent 


The FFMakeDName call converts the name pointed to by ioNamePtr into a legal 
ProDOS directory name. | 


This call does not check to see if the directory name already exists. 
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FFXSetCatinfo 
The FFXSetCatInfo call uses the XCInfoPBRec record described below: 
XCInfoPBRec = RECORD 


CInfo : CInfoPBRec; 
{Input to FFXSetCatInfo; this 1s the same record used by FFSetCatInfo: 
you can use this call to perform all the functions of FFSetCatInfo) 


CASE xfs : XFSType OF 
prodos : 
(The following two fields are also used as input to FFXSetCatInfo] 
(auxtype : INTEGER; 
access : SIGNEDBYTE; 


(The remaining fields are used by FFSetCatInfo, but are ignored by 
FFXSetCatInfo! 


storagetype : SIGNEDBYTE; 

version : SIGNEDBYTE; 

minvers : SIGNEDBYTE) 
END; 
The case selector for this variable record is defined as follows: 
TYPE 


XFSType = ( Mac, ProDOS, MSDOS ); 


The fields in this record are used as described below. Of these fields, only auxtype and 
access can be changed by translators. 


CInfo ^ A pointer to the standard CInfoPBRec record used by the FFGetCatinfo 
and FFSetCatInfo calls 

auxtype The auxiliary file type for a ProDOS file 

access Contains flags that control access to a ProDOS file: 


$80—the file can be deleted 

$40—the file can be renamed 

$20—the file has changed since it was last backed up 
$02—the file can be written to 
$01—the file can be read 
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FFRename 


If the new name does not follow the ProDOS convention, the FFRename call will fail 
and return a “Bad filename," “Bad directory name," or "Bad volume name" error. 


E A 


FFSetCatinfo 


For the FFSetCatInfo call, the following fields are ignored for files: 
o ioFlFndrInfo 
© fdLocation 
o fdFldr 
a fdFlags 
o ioFIXFndrInfo 
Jg ioFlClpSiz 
o ioFIBkDat 
The following fields may be set for files: 
o ioFlFndrinfo 


o fdtype—a four-byte string that reflects ProDOS file type. The string contains the 
ASCII equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be ‘FC '. There is one exception: the fdtype field 
for a TXT ($04) file is "TEXT". If the fdtype string does not follow this 
convention, the file type is not changed. (Note: To set the auxiliary file type for a 
ProDOS file, use the FFXSetCatInfo call.) 


OQ fdcreator—'pdos' 
O ioFlCrDat—creation date 
o ioFlMdDat—modification date 
c ioFlAttrrib—if this field is set to $01, sets the file locked attribute for the file. 
The following fields are ignored for directories: 
o ioDrUsrWds 
o ioDrFndrinfo 
O ioDrMdDat 
o ioDrBkDat 
The following fields may be set for directories: 
O ioNamePtr—if a directory is specified by ioFDirindex 
BG ioDrCrDat—creation date 


EO 


FFSetEOF 
The FFSetEOF call works the same as on the Macintosh. 
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Chapter 5 


Calling the 
MS-DOS File System 
From Translators 
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FFXGetCaiinfo 
The FFXGetCatinfo call uses the XCInfoPBRec record described below: 
XCInfoPBRec = RECORD 


CInfo : CInfoPBRec; 
{Input to FFXGetCatInfo. This 1s the same record used by 
FFGetCatInfo, and you can use this call to perform all the functions 
of FFGetCatinfol 


CASE xfs : XFSType OF 
prodos : 
(These fields are returned by FFXCatInfo) 
(auxtype : INTEGER; 
access : SIGNEDBYTE; 
storagetype : SIGNEDBYTE; 
version : SIGNEDBYTE; 
minvers : SIGNEDBYTE) 
END; 
The case selector for this variable record is defined as follows: 
TYPE 
XFSType = (Mac, ProDOS, MSDOS); 
The fields in this record are used as described below: 


CInfo The standard CInfoPBRec record used by the FFGetCatinfo and 
FFSetCatInfo calls; using this record, you can perform any of the 
functions provided by the FFGetCatinfo call 


auxtype The auxiliary file type for a ProDOS file 
access Contains flags that control access to a ProDOS file: 
$80—the file can be deleted 


$40—the file can be renamed 

$20—the file has changed since it was last backed up 
$02—the file can be written to 
$01—the file can be read 


storagetype Describes the ProDOS directory entry for the file: 


$1—the file is a seedling (that is, it has only one data block) 

$2—the file is a sapling (that is, one containing from 2 to 256 data 
blocks) 

$3—the file is a tree (that is, one containing from 257 to 32768 data 
blocks) 

$D—the file is a subdirectory 


version The version of ProDOS under which this file was created 


minvers The minimum version of ProDOS that can gain access to this file 
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Limitations of the MS-DOS file system 


The MS-DOS file system has a number of limitations that apply to all calls: 


o Working directories are not implemented in any form. All volume reference 
numbers must refer to actual volumes, not directories within volumes. 


C Partial pathnames are not supported. The MS-DOS file system recognizes only 
volume names and filenames. 


o A maximum of eight files may be open at any one time. 


o MS-DOS operations are always performed synchronously. The IoCompletion field 
of the parameter block is always ignored. The Async parameter in file system calls is 
also ignored. 

O The root directory of every volume has a directory ID of 2. 


C All calls support filenames, but not pathnames. For example, 
HD:MyFolder:MyFile cannot be passed as a parameter to an MS-DOS file system 
routine, but MyFile can. 


Cl As with all Apple File Exchange file systems, the HFS version of each call is the one 
that is implemented. You must pass pointers to PBHParamBlockRec records where 
appropriate and include values in all the fields that are necessary for each call. 


File system calls not supported by the MS-DOS file system 


Table 2-7 in Chapter 2 lists all the available file system calls and the corresponding 
Msg value for each call. Table 5-1 lists those calls that are not supported by the 
MS-DOS file system. 


Table 5-1 


File system cails not supported 
by the MS-DOS file system 


Name of call 


FFAllocate 
FFAllocContig 
FFCloseWD 
FFGetWDInfo 
FFLockRange 
FFOpenRF 
FFOpen WD 
FFRstFLock 
FFSetEOF 
FFSetFLock 
FFSetFVers 
FFSetVInfo 
FFUnlockRange 


Msg value 


19 
20 


12 


*Note that you can lock and unlock 
files by using the FFSetCatinfo call. 
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FFGetCatinfo 
For the FFGetCatInfo call, the following fields return 0 for files: 


m 
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ioFlFndrinfo 
o fdLocation 
a fdFldr 
ioF1StBik 
ioFIRStBlk 
ioFIXFndrInfo 
ioFIRLgLen 
ioFIRPyLen 


The following fields return values for files: | 


- 
o 
m 


00 00 D 


ioNamePtr—if file is specified by ioFDirIndex 
ioFRefNumber-—file reference number, if the file is open 
ioFlAttrib—file attributes; reflects the MS-DOS characteristic bits: 
o $01—if the file is locked 
O All other bits are cleared. 
ioFlFndrinfo 
o fdtype 
"EXT —if the file is determined to be a text file 
'BINA'—all other files 
Note: Like other MS-DOS files, MS-DOS text files do not have an explicit file type. 
FFGetFInfo uses the following algorithm to determine if a file is an MS-DOS text file: 
1. It reads the first 512 bytes of the file (or all of the file if it contains less than 512 
bytes). 
2. Next, it counts the number of printable characters (those characters between 
space and tilde in the ASCII character set) and compares the result to the number 


of nonprinting characters (all characters that aren't in the range between space 
and tilde, including all characters whose high-order bits are set). 


3. If the number of printable characters is at least twice the number of nonprinting 
characters, it determines that the file is a text file. 


Because this algorithm does not always produce the correct result, translators must 
be prepared to handle cases where a file is incorrectly identified. 


o fdcreator-—'mdos' 


CO fdFlags—if the MS-DOS hidden attribute ($02 in byte 11 of an MS-DOS directory 
entry) is set for a file, the fdFlags invisible flag is set. If the MS-DOS system 
attribute ($04 in byte 11 of an MS-DOS directory entry) is set for a file, the fdFlags 
system flag is set. 


ioDirID—file number 
ioFiLgLen—data fork logical length 
ioFIPyLen—-data fork physical length 
ioFlCrDat—creation date 
ioFIBkDat—same as creation date 
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This chapter describes the MS-DOS foreign file system provided by Apple File 
Exchange. It includes 


C an overview of the file system and its operation 
D a list of the file system's limitations 


o details of the ways in which MS-DOS file system calls differ from the corresponding 
Macintosh Hierarchical File System (HFS) calls. For information about HFS, see 
"The File Manager" chapter in Volume IV of Inside Macintosh. 


EAE 
About the MS-DOS file system 


MS-DOS is the operating system created by Microsoft for the IBM PC and compaüble 
computers. Recent versions of MS-DOS provide a hierarchical, tree-structured file 
system that is similar in many ways to the Macintosh Hierarchical File System (HFS). 
Apple File Exchange supports versions of MS-DOS numbered 2.0 and higher. 


Translators should never try to read MS-DOS disk structures directly. Instead, they 
must use the MS-DOS foreign file system resource provided by Apple File Exchange. 
There are two important reasons for using this resource: 


1. Apple File Exchange can properly handle disk swapping and other events. 

2. Translators use a single function, CallFS, to perform any of the operations provided 
by the file system. The operation performed is determined by the value of the 
CallFS Msg parameter. 


Translators also use the CallFS function to call the other file systems supported by 
Apple File Exchange. The calls provided by CallFS are modeled after Macintosh HFS 
calls and are the same for ali file systems. Because there are important differences 
between the MS-DOS and HFS file systems, the results of many MS-DOS calls are 
different from the corresponding HFS calls. When there are differences, the 
differences are explained in the next section and in the descriptions of the calls. 


If you have already read Chapter 4, you will notice that the MS-DOS foreign file system 
is very similar to the ProDOS foreign file system. Although many of the descriptions in 
this chapter are identical to those in Chapter 4, there are important differences 
between the ProDOS and MS-DOS versions of certain calls. Before using any MS-DOS 
routine, be sure to read its description carefully. 
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o ioFDirindex = -1 

INPUT . 

o ioNamePtr—ignored 

o ioDirID—if 0, use ioVRefNum for volume and directory, else use ioDirID for 
directory 

OUTPUT 

o ioNamePtrA—retums name of directory specified by ioVRefNum and ioDirID 

c ioDir[D—returns number of directory (ioDrDirID) specified by ioVRefNum and 
ioDirID 

o ioFlPar[D—returns directory number of parent of directory in question 





FFGetEOF 
The FFGetEOF call behaves like the corresponding Macintosh call. 
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FFGelFinfo 


For the FFGetFinfo call, the following fields return 0: 
o ioFlFndrinfo 
o fdLocation 
o fdFidr 
© ioFIStBlk 
OQ ioFIRStBIk 
© ioFIRLgLen 
o ioFIRPyLen 
The following fields return values: 
o ioNamePtr—if file is specified by ioFDirlndex 
o ioFRefNumber—file reference number, if the file is open 
C ioFlAttrrib—file attributes; reflects the MS-DOS characteristic bits: 
o $01-f the file is locked 
O All other bits are cleared. 
Q ioFlFndrInfo 
D fdtype 
"TEXT —if the file is calculated to be a text file 
'BINA'—-all other files 


Note: Like other MS-DOS files, MS-DOS text files do not have an explicit file type. 
FFGetFInfo uses the following algorithm to determine if a file is an MS-DOS text file: 


1. It reads the first $12 bytes of the file (or all of the file if it contains less than 512 
bytes). 
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MS-DOS file system calls 


The following sections describe the differences between MS-DOS foreign file system 
calls and the corresponding Macintosh file system calls. 
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FFClose 
The FFClose call behaves like the corresponding Macintosh call. 


L E M 


FFCreate 


The FFCreate call creates a file. To set the attributes of a file, use the FFXSetCatinfo 
call. 


If the name of the file created does not conform to MS-DOS conventions, the FFCreate 
call will fail and return the error “Bad filename." 


FFCreate may fail with the error -9 if the file's full pathname is greater than the 
MS-DOS limit of 64 characters. 
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FFDelete 
The FFDelete call behaves like the corresponding Macintosh call. 


e—a 


FFDirCreate 
The FFDirCreate call behaves like the corresponding Macintosh call. 


If the name of the directory created does not conform to MS-DOS conventions, the 
FFDirCreate call will fail and return the error “Bad filename." 


FFDirCreate may fail with the error -9 if the directory's full pathname is greater than 
the MS-DOS limit of 64 characters. 


€ Note Translators should only use FFDirCreate to create temporary directories 
during a translation. If a translator does create a directory, it must delete the 
directory before finishing the translation. 


NNNM MM 


FFFiushFile 
The FFFlushFile call behaves like the corresponding Macintosh call. 
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FFFiush Vol | 
The FFFlushVol call behaves like the corresponding Macintosh call. 
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ioVAtrb 

ioVNmFls 

ioVClpSiz 

ioVSigWord 

ioVDrvinfo 

ioVDRefNum 

ioVFilCnt 

ioVDirCnt 

The following fields return information: 

o ioNamePtr—if ioVRefNum is used to specify a volume, returns name of volume 
specified 

0 ioVRefNum—if ioNamePtr or drive number is used to specify a volume, returns 

reference number of volume 


ioVNmAJBIks—number of allocation blocks 
ioVAIBIkSiz—allocation block size, same as cluster size for volume 
icAIBlSt—first block in volume block map 

ioVFrBlk— number of unused allocation blocks 
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Do 0 0 
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FFMakeDName 

The FFMakeDName call accepts the following fields from a HParamBlockRec record as 
input: | 

C ioNamePtr—a pointer to a directory name 

o ioVRefNum—the volume reference number for the volume containing the directory 
o ioFIParID—ID of the specified directory's parent 


The FFMakeDName call converts the name pointed to by ioNamePtr into a legal 
MS-DOS directory name. 


This call does not check to see if the directory name already exists. 





FFMakeFName | 


The FFMakeFName call accepts the following fields as input: 

O ioNamePtr—a pointer to a filename 

o ioVRefNum—the volume reference number for the volume containing the file 
o ioFIParID—ID of the specified file's parent 


The FFMakeFName call converts the name pointed to by ioNamePtr into a legal 
MS-DOS filename. 


This call does not check to see if the filename already exists. 
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o ioFIMdDat—same as creation date if the archive bit has not been changed, 
otherwise (creation date + 1) 


o ioFIParID—ID of parent of specified file (2 indicates parent is root; 0 indicates file 
is already at root) 


a ioFIClpSiz—O 
The following fields return 0 for directories: 
ioFRefNum 
ioDrUsrWds 
ioDrFndrInfo 
ioDriCrDat 
ioDrMdDat 
ioDrBkDat 
ioFlAttrib 
ioDrBkDat 
The following fields return values for directories: 
ioNamePtr—if directory is specified by ioFDirIndex 
ioDrDirID—directory ID (root is indicated by 2) 
ioDrNmFls—number of files and directories in this directory 
ioDrCrDat—creation data 
ioDrMdDat—same as creation date 
ioDrParID—ID of parent of specified file (2 indicates the root; 0 indicates no 
parent, that is, this is already the root) 
The PBGetCatinfo function is powerful, but it may be difficult to understand. Here is a 
summary of what it does: 
o ioFDirlndex = n (> 0) 
INPUT 
o ioNamePtr—ignored for input 
o- ioDirID—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirID 
for directory 
OUTPUT 
c ioNamePtr^—returns name of mh file or directory 
o ioDir[D—returns file number GoFINum) or directory number CGioDrDirID) 
n ioFiParID—returns directory number of parent of mth file or directory 
o ioFDirlndex = 0 
INPUT 
4 ioNamePuA—contains name of file in question (error if ioNamePtr = NIL) 


o ioDirID—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirID 
for directory 


OUTPUT 

o ioNamePtr^—unchanged 

o ioDirID—returns file number (ioFINum) or directory number (ioDrDirID) 

D ioFiPariD—retums directory number of parent of file or directory in question 


a aauuool]5 cU 
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The following fields may be set for files: 
m ioFlAttrib—file attributes; reflects the MS-DOS characteristic bits 
a $01—if the file is locked 
D All other bits are cleared. 
o ioFlFndrInfo 
O fdtype—The following file types are ignored: 
‘TEXT’, 'BINA', all nulls 
o ioFlFndrInfo 
CO fdcreator—'mdos' or all nulls (same as 'mdos') 
G ioFlCrDat-—creation date 
o ioFlBkDat—same as creation date 
o ioFiMdDat—if the archive bit has not been changed, same as creation date 
The following fields are ignored for directories: 
ioDrUsrWds 
ioDrFndrinfo 
ioDrCrDat 
ioDrMdDat 
ioDrBkDat 
ioFlAttrib 
ioNamePtr 


D oonguozdidtuü 





FFSetFinfo 
For the FFSetFInfo call, the following fields are ignored: 
o ioFiFndrinfo 
OG fdLocation 
o fdFidr 
o fdtype 
OQ fdcreator 
o fdFlags 
The following fields may be set 
O ioFiFndrinfo 
a ioFlCrDat—creation date 
O ioFlBkDat-—sarne as creation date 
C ioFlMdDat—if the archive bit has not been changed, same as creation date 





FFSetFPos 
The FFSetFPos call behaves like the corresponding Macintosh call. 
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2. Next, it counts the number of printable characters (those characters between 


space and tilde in the ASCII character set) and compares the result to the number 


of nonprinting characters (all characters that aren't in the range between space 
and tilde, including all characters whose high-order bits are set). 


3. If the number of printable characters is at least twice the number of nonprinting 
characters, it determines that the file is a text file. 


Because this algorithm does not always produce the correct result, translators must 
be prepared to handle cases where a file is incorrectly identified. 


© fdcreatoc—'mdos' 

o fdFlags—if the MS-DOS hidden attribute ($02 in byte 11 of an MS-DOS directory 
entry) is set for a file, the fdFlags invisible flag is set. If the MS-DOS system 
attribute ($04 in byte 11 of an MS-DOS directory entry) is set for a file, the fdFlags 
system flag is set. 

ioDirID—file number 

ioFlILgLen—-data fork logical length 

ioFIPyLen--data fork physical length 

ioFlCrDat-—reation date 

ioFIBkDat—same as creation date 

ioFIMdDat—if the archive bit has not been changed, same as creation date 


o0o00ag0 0 


nn MM 


FFGetFPos 
The FFGetFPos call behaves like the corresponding Macintosh call. 


a 


FFGetVinfo 


The FFGetVInfo call returns one of the following as the function result 
o If the value passed in the ioVolIndex field is greater than 0, the call returns an error. 


O If the value passed in the ioVolIndex field is equal to 0, the call returns information 
about the volume specified by ioVRefNum. 


o If the value passed in the ioVolIndex field is less than 0, the call uses ioNamePtr and 
ioVRefNum in the standard way. 

The following fields return 0: 

ioVFndrinfo 

ioVCrDat 

ioVLsMod 

ioVBitMap 

ioAllocPtr 

io VNxtCNID 

ioVFSID 

ioVSeqNum 

ioVWrCnt 

ioVBkUp 
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FFXSetCatinfo 
The FFXSetCatInfo call uses the XCInfoPBRec record described below: 
XCInfoPBRec = RECORD 
CInfo : CInfoPBRec; (Input to FFXSetCatInfo} 
CASE xfs : XFSType OF 
msdos : 
(The following two fields are also used as input to FFXSetCatInfo) 
(attrib : SIGNEDBYTE; 
filler4 : SIGNEDBYTE) 
END; 
The case selector for this variable record is defined as follows: 
TYPE 


XFSType = (Mac, ProDOS, MSDOS); 


The fields in this record are used as described below. These fields cannot be changed 
by translators. 


CInfo A pointer to the standard CInfoPBRec record used by the FFGetCatinfo and 
FFSetCatinfo calls. 


attrib This field contains attribute flags for an MS-DOS file. These flags are 


$01—a read-only file 

$02—a hidden file (that is, one hidden from normal directory searches) 

$04—a system file (the file is also hidden from normal directory searches) 

$08—an entry that contains the volume label in the first 11 bytes 

$10—an entry that defines a subdirectory (that is, this entry is hidden from 
normal directory searches) 

$20—archive flag: set when the file is written to and closed 


All other bits are reserved. Set these bits to 0. 
fillerá This field is reserved for future use. 
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FFOKDName 

The FFOKDName call accepts the following fields as input 

o ioNamePtr—a pointer to a directory name 

o ioVRefNum-—the volume reference number for the volume containing the directory 
C ioFIParID—ID of the specified directory's parent 


The FFOKDName call returns noErr if the name pointed to by ioNamePtr is a legal 
MS-DOS directory name. 


This call does not check to see if the directory name already exists. 


LT 


FFOKFName 
The FFOKFName call accepts the following fields as input: 
o ioNamePtr—a pointer to a filename 
tl ioVRefNum—the volume reference number for the volume containing the file 
o ioFIParID—ID of the specified file's parent 


The call returns noErr if the name pointed to by ioNamePtr is a legal MS-DOS 
filename. 


This call does not check to see if the filename already exists. 


i ——— 


FFOpen 
The FFOpen call behaves like the corresponding Macintosh call. 


ip à —— M 


FFRead 
The FFRead call behaves like the corresponding Macintosh call. 


a (MÀ M—Ó—M 


FFRename 


If the new name does not follow the MS-DOS convention, the FFRename call will fail 
and return a “Bad filename,” “Bad directory name," or "Bad volume name" error. 


ee a py i RR EA ——— 


FFSetCatinfo 
For the FFSetCatInfo call, the following fields are ignored for files: 
o ioFlFndrinfo 
o fdLocation 
a fdFldr 
OG ioFlXFndrInfo 
o ioFlClpSiz 
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Appendix A 


Pascal Conventions 
for Translators 


This appendix describes the treatment of different kinds of parameter and function 
results by Macintosh Pascal. It includes descriptions of all the basic Pascal data 


types. 








External calling conventions 


This section describes the treatment of parameters, function results, and register 
conventions. 





Parameters 


Parameters are evaluated from left to right and are pushed onto the stack in that order 
as they are evaluated. The called procedure is responsible for removing the 
parameters from the stack. All VAR parameters are passed as pointers to the actual 
storage location. Note that in cases of byte-wide parameters, the pointer may have 
an odd value. 


Non-VAR parameters are passed in the following ways, depending upon the type of 
the parameter. Values of type Boolean, elements of an enumerated type with fewer 
than 128 elements, and subranges within the range —128..127 are passed as signed 
byte values. (They are pushed as bytes; the MC68000 allocates two bytes for each byte 
on the stack.) The called procedure expects Boolean parameters to be in the range 
0..1. 


Values of types integer and char and all other enumerations and subranges are 
passed as signed word values. Pascal char values are expected to be in the range 
0..255; the upper half of this range is used for special characters. Pointers and 
longint values are passed as signed 32-bit values. 





FFWrite 
The FFWrite call behaves like the corresponding Macintosh call. 


en A e A e O  ————— 


FFXGetCatinfo 
The FFXGetCatInfo call uses the XCInfoPBRec record described below: 
XCInfoPBRec = RECORD 


CInfo : CinfoPBRec; 
{Input to FFXGetCatInfo. This is the same record used by FFGetCatInfo, 
and you can use this call to perform all the functions of FFGetCatInfo} 


CASE xfs : XFSType OF 
msdos : 
(These fields are returned by FFXGetCatinfo} 
(attrib : SIGNEDBYTE; 
filler4 : SIGNEDBYTE) 
END; 
The case selector for this variable record is defined as follows: 
. TYPE 
XFSType - (Mac, ProDOS, MSDOS); 


The fields in this record are used as described below. These fields cannot be changed 
by translators. 


CInfo The standard CInfoPBRec record used by the FFGetCatInfo and FFSetCatInfo 
calls. 


attrib This field contains attribute flags for an MS-DOS file. These flags are 


$01—a read-only file 

$02—a hidden file (that is, one hidden from normal directory searches) 

$04—a system file (the file is also hidden from normal directory searches) 

$08—an entry that contains the volume label in the first 11 bytes 

$10—an entry that defines a subdirectory (that is, this entry is hidden from 
normal directory searches) 

$20—archive flag: set when the file is writen to and closed 


Other bits are reserved. 
fillerá X This field is reserved for future use. 
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Real parameters 


Values of types real, double, comp, and extended are passed as pointers to extended 
values. The Compiler does this in a reentrant way by allocating a temporary location 
in the caller’s activation record, converting the parameter value to an extended value 
in this location and passing a pointer to this location. The called procedure then 
aliocates a local location of the declared type and converts the extended value, using 
the pointer, into the location and type. 


Structured parameters 


Arrays, strings, and records whose size is less than or equal to four bytes are passed 
by pushing their value (either a word or a long) onto the stack. Larger arrays, strings, 
and records (as well as extended values, as mentioned above) are passed as a pointer 
to the value; for reentry purposes, the Compiler emits code in the called procedure 
to copy the value to a local storage location. 


Sets are passed by rounding the set size up to the next whole word, if necessary, and 
then pushing the set value so that the lowest-order word is pushed last. In the case of a 
byte-width set, the called procedure will only access the low-order half of the word 


pushed. 





Function results 


Function results are returned by value or by address on the stack. Space for the 


function result is allocated by the caller before the parameters are pushed. 


The caller 


is responsible for removing the result from the stack after the call. Table A-2 lists the 
conventions for passing each type of function result. 





Table A-2 

Function resuit passing conventions 

Result type Pascal caller... Pascal callee... After the call 

Boolean Allocates Returns byte value: Pops byte 
word range 0..1 

Enumeration: Allocates Returns byte value: Pops byte 

range 0..127 word range 0..127 

Enumeration: Allocates Returns word value: Pops word 

range 0..32767 word range 0..32767 

Char Allocates Returns word value: Pops word 
word range 0..255 

Subrange: Allocates Returns byte value: Pops byte 

range —128..127 word range —128..127 

Subrange: Allocates Returns word value: Pops word 

range -32768..32767 word range —32768..32767 

Integer Allocates Returns word value: Pops word 
word range —32768..32767 

(continued) 
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For types Boolean, char, and integer, and enumerated and subrange types, the 
caller allocates a word on the stack to make space for the function result. Values of 
type Boolean, enumerated types with fewer than 128 elements, and subranges within 
the range -128..127 are returned as signed byte values. The value goes in the low- 
address byte, which is the most significant byte of the word. The calling procedure 
expects Boolean results to be in the range 0..1. 


Integer and char values and all enumerated and subrange types not covered above 
are returned as signed word values. Pascal char values are expected to be in the range 
0..255; the upper half of this range is used for special characters. 


For pointers, longint, and the real types, the caller allocates a long on the stack to 
make space for the function resuit Pointers and longint values are returned as signed 
32-bit values. Values of type real are returned as 32-bit real values. For double, 
comp, and extended types, and for sets, arrays, strings, and records greater than 
four bytes in size, the caller pushes a pointer to a temporary location. 


For one-byte sets and for arrays, strings, and records whose size is one word, the 
caller allocates a word on the stack. For sets, arrays, strings, and records whose size is 
two words, the caller allocates a long word on the stack. One-byte sets are returned as 
a byte value. Sets, arrays, strings, and records whose sizes are one or two words are 
returned as either a word or a long word. 





Register conventions 


Registers DO, D1, D2, AO, and Al are considered scratch registers and are not 
preserved across procedure calls. All other registers are preserved by the called 
routine. Register A5 is the global data pointer, register A6 the local frame pointer, 
and register A7 the stack pointer. 
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Table A-1 lists the Pascal parameter passing conventions. 


Table A-1 


Parameter passing conventions 


Parameter type 


Boolean 


Enumeration: 
range 0..127 


Enumeration: 
range 0..32767 


Char 


Subrange: 
range ~128..127 


Subrange: 
range -32767..32767 


Integer 


Longint 
Pointer 
Real 


Double 


Comp 


Extended 


Array, Record, 
String S four bytes 


Array, Record, 
String > four bytes 


Set 


Pascal cailer... 


Pushes byte: 
range 0..1 

Pushes byte: 
range 0..127 


Pushes word: 
range 0..32767 


Pushes word: 
range 0..255 
Pushes byte: 
range -128..127 


Pushes word: 
range -32767..32767 


Pushes word: 
range -32767..32767 


Pushes long 
Pushes long 


Converts to extended, 
pushes address of 
extended 


Converts to extended, 
pushes address of 
extended 


Converts to extended, 
pushes address of 
extended 


Pushes address of 
extended 


Pushes value 
(word or long) 


Pushes address 
of value 


Pushes set value 
rounded to whole 
number of words 


Pascal callee... 


Accesses byte: 
range O..1 


Accesses byte: 
range 0..127 


Accesses word: 
range 0..32767 


Accesses word: 
range 0..255 


Accesses byte: 
range ~128..127 


Accesses word: 
range -32767..32767 


Accesses word: 
range -32767..32767 


Accesses signed long value 
Accesses long 


Converts extended on stack 
to local real, accesses local 
value 


Converts extended on stack 
to local double, accesses 
local value 


Converts extended on stack 
to local comp, accesses local 
value 


Copies extended to local 
extended, accesses local 
value 


Accesses value (word or long) 


Copies value to local, 
acoesses local 


Accesses value on stack 
(Note: Use word or long for 
those sizes, accesses 
low-order half of word for 
byte-size set.) 
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Appendix B 











Apple File Exchange 
Messages 


The messages listed in this appendix are included in a resource built into Apple File 
Exchange. They are available for use by translators. 











Resource description for Apple File Exchange 
messages 

rescurce"STRé' (150) { { 

f**/ 


/* General System Errors (VBL Mgr, Queveing, Etc.) */ 


{ref 

/* no£rr EQU O0 0 for success */ 

/* qgrr EQU -1 */ "queue element not found during deletion"; 

/* vTypErr EQU -2 */ "invalid queue element"; 

/* corErr EQU -3 */ "core routine number out of range"; 

/* unimpErr EQU -4 */ "unimplemented core routine"; 

/* don't know EQU -5, -6 */ "unknown problem"; "unsupported function"; 

/* format problem  EQU -7 */ "Cannot write directory on this type of disk"; 

/*  seNoDB EQU -8 */ "no debugger installed to handle debugger command"; 
ps" 


/* Special for other functions */ 

Aii 

/* EQU -9 */ "total pathname length is too long"; 
[xy 


/* Special for file server */ 


/**/ 

/* EQU -10 v/ "access denied"; 

/* don't know -11...-16 */ NW WE WEM MA RA TEE 
/[**/ 


B-1 


Table A-2 (continued) 
Function result passing conventions 


Result type 


Longint 


Real 


Doubie 


Comp 


Extended 


Array, String, 
Record S four bytes 


Array, String, 
Record > four bytes 


Set: one byte 


Set: one word 


Set: two words 


Set > two words 


Allocates 
long word 


Allocates 
long word 


Pushes 
address 

of doubie 
temporary 


Pushes 
address 

of comp 
temporary 


Pushes 
address of 
extended 
temporary 
Allocates 
word or 
long word 
Pushes 
address of 
temporary 
Allocates 
word 


Allocates 
word 


Allocates 
long word 


Pushes address 
of temporary 


Pascal callee... 


Returns long word 
value: range is 
signed 32 bits 


Returns real value 


Puts double result 
in temporary 


Puts double result 
in temporary 


Puts extended result 
in temporary 


Returns word 
or long word 


Puts result in 
temporary 


Returns byte value 
of result 


Returns word value 
of resuit 


Returns long word 
value of result 


Puts result in 
temporary 


After the cail 


Pops long word 


Pops real value 


Pops temporary 
address, accesses 
temporary value 


Pops temporary 
address, accesses 
temporary value 


Pops temporary 
address, accesses 
temporary value 


Pops word or 
long word 


Pops temporary 
address, accesses 
temporary value 


Pops byte 
Pops word 
Pops long word 


Pops temporary 
address, accesses 
temporary value 


Note: Pascal does not assume any initial value for memory space allocated to a function result 
unless it is a pointer to a type that occupies more than four bytes of memory. 
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gfpErr EQU -52 */ "problem with getting file position”; 


volOffLinErr EQU -53 */ "volume not on line (was Ejected)"; 

permErr EQU -54 */ “permission error; access denied to file/folder"; 
volOnLinErr SQU -55 */ "drive volume already on-line at MountVol"; 

nsDrvErr EQU -56 */ "no such drive (tried to mount a bad drive num)"; 
noMacOskErr EQU -57 */ "not a correct diskette (signature bytes are wrong)"; 
extFSErr EQU -58 */ "voiume in question belongs to an external file system"; 
fsRnErr EQU -59 */ 


"during rename the old entry was deleted but could not be restored”; 


badMDBErr EQU -60 */ "bad master directory block"; 

wrPermErr EQU -61 */ "write permissions are incorrect"; 

unknown EQU -62,-63 */ "";"*; 

noDriveErr EQU -64 */ "drive not installed"; 

offLinErr EQU -65 */ "read or write requested for an off-line drive"; 

noNybErr EQU -66 */ "couldn't find disk data in 200 tries — bad disk"; 
noAdrMkErr EQU -67 */ "couldn't find valid address mark on disk — bad disk"; 
dataVerErr EQU -68 */ "read verify compare failed — disk won't hold its data"; 
badCkSmErr EQU -69 */ "address mark checksum didn't check — disk is going bad"; 
badBtSlpErr EQU -70 */ "bad address mark bit slip nibbles - disk is damaged"; 
noDtaMkErr EQU -71 */ “couldn't find a data mark header — disk is damaged"; 
badDCkSum EQU -72 */ "bad data mark checksum — disk has been damaged”; 
badDBtSlp EQU -73 */ "bad data mark bit slip nibbles — disk is damaged"; 
wrUnderRun BQU -74 */ “write underrun occurred — disk speed may need adjustment"; 
cantStepErr EQU -75 */ “step handshake failed - disk drive may need calibration"; 
tkOBadErr EQU -76 */ 


"track 0 detect doesn't change — are you sure there's a disk there?*; 
initIWMErr EQU -77 */ 


"unable to initialize disk interface — check cables to disk drive"; 


twoSideErr EQU -78 */ "tried to read 2nd side on a l-sided drive"; 
spdAd jErr EQU -79 */ "unable to correctly adjust disk speed"; 
seekErr EQU -80 */ 


"unable to seek to correct track on disk — disk may be going bad"; 


sectNFErr EQU -81 */ . "sector number never found on a track — disk is going bad"; 
fmtlErr EQU -82 */ "can't find sector O after track format — disk may be bad"; 
fmt2Err EQU -83 */ "can't get enough sync — cannot format disk"; 

VerErr EQU -84 */ "track failed to verify — disk won't hold data" 
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Appendix C 


An Example 
of a Translator 


On the following pages, you'll find listings for Macintosh Programming Workshop 
MPW) files that make up a sample translator. This translator opens up the resource 
fork of a Macintosh file and copies all resources of the type 'STR4' to a text file on any 
of the file systems. You can use these files as the starting point for a new transiator. 


The files listed are 


Q 
a 
a 


0 
a 
Q 


Q 


Example.p, written in MPW Pascal, which contains the body of the translator 
AFETrans.p, which contains Pascal declarations used by Example.p 


Example.a, written in 68000 assembly language, which contains the required 
header for the translator 


Example.r, a resource description file for the resources used by the translator 
Example, file 7—which, when run, creates the translator 


doit, an MPW shell script created by Example, file 7 for assembling, compiling, 
and linking the files 


Example.make, the MAKE file used to control the building of the translator 


A disk called ExampleTrans is provided with this manual. It includes the files listed 
above, as well as these additional files: 


D 
a 


Example.rsrc, the resource file for the translator 
Example Translator, the finished translator 


/* I/O System Errors */ 


del d 

/* controlErr EQU -17 */ "problem with control call"; 

/* statusErr EQU -18 */ "problem with status call"; 

/* readErr EQU -19 */ "problem reading"; 

/* writErr EQU -20 */ "problem writing”; 

/* badUnitErr EQU -21 */ "bad unit number used"; 

/* unitEmpCyErr EQU -22 */ "empty unit accessed"; 

/* openErr EQU -23 */ “problem while opening"; 

/* closErr EQU -24 */ "problem while closing"; 

/' dRemovErr EQU -25 */ "tried to remove an open driver"; 
/* dInstErr EQU -26 */ "DrvriInstall couldn't find driver in resources"; 
/* abortErr EQU -27 */ "IO call aborted by KillIO": 

/* notOpenErr EQU -28 */ "driver not opened"; 

/* don't know EQU -29..-32 */ xiu inicr ns ipia) 

dade J 


/* File System error codes */ 


iia i 

/* dirFulErr EQU -33 */ "Directory is full"; 

fe dskFulErr EQU -34 */ "disk is full": 

/* nsvErr EQU -35 */ "no such volume"; 

/* ioErr EQU -36 */ "Input/Output error"; 

/* bdNamErr EQU -37 */ “bad name (possibly too long, bad characters, etc.)"; 
/* fnOpnErr EQU -38 */ "File not open"; 

/* eofErr EQU -39 */ "End of file"; 

/* posErr EQU -40 */ "tried to position to before start of file"; 

/* m£ul£rr EQU -41 */ "memory full (open) or file won't fit (load)"; 

/* tmfoErr EQU -42 */ "too many files open"; 

/"  fnfErr EQU -43 */ "File/Folder not found"; 

/* wPrErr EQU -44 */ "diskette is write protected"; 

/* fLekdErr EQU -45 */ "file is locked"; 

/* vwLckdErr EQU -46 */ "volume is locked"; 

/* £fBsy£rr EQU -47 */ "file is busy (or folder still contains files)"; 
/* dupFNErr EQU -48 */ "file/folder of that name already exists"; 

/* opWrErr EQU -49 */ "file already open with write permission"; 

/* paramErr EQU -50 */ "problem with parameter list sent to file system"; 
/* rfNumErr EQU -51 */ "file reference number error”; 
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{ RECTAL AAAAA AA TARAS REET d dT OPI re USER ERAT RENNES ES 


* * 
* constants for dialog box M 
* these are the item numbers for the objects in the options dialog box * 
* t 


d xod dn e i e ee e fe EE ERECTA EAHA e d ee e e e e e e eie fe etd dn) 


d OK = i; 
d Cancel = 2; 
d text = 3; 


d MWradio = 4; 

d MSWradio = 5; 
d MPWradio = 6; 
d MDSradio = 7; 
d otherRadio = 8; 
d Micon = 3; 

d MSWicon = 10; 
d MPWicon = 11; 
d MDSicon = 12; 
d otherText = 13; 


(sc RE PR edo OUR ICI n OR eR Ro ROI POR DIU RIO UR PORC ROI RC 


* * 
* Miscellaneous Constants * 
* *" 


MPPPIIIIIIIILIZAPRRALDRRRRIRRILRRARERLRRIRSRSRRRRRRRRILEERREREEAL LEE LR ER 


tMCMC = 1; { Mac to Mac translation } 
tMCPD - 2; ( Mac to ProDOS translation ) 
tMCMS = 3; { Mac to MS-DOS translation } 


[sace AT SALE RR Y dedos AARNE EH ES 


+ The following are offsets from the MacWrite * 
* button in the options dialog box nl 
eognfetemdedeseieiet dedere dede dete fedet dede ede den) 
tMacWrite = 0; ( MacMrite } 

tMSWord 1; ( Microsoft Word } 
tMPW = 2; ( MPW ) 

tMDS = 3; ( MOS 68000 } 

tother = 4; { other ) 


( sciiicet dedi eicdnicdnde eosdem di e dod e 


* The following are creator names for the apps * 
* in the options dialog box * 
Yes dem dose t t i d kE tdi eei dede fede de dem) 
fMacWrite = 'MACA'; ( MacWrite ) 

fMSWord = 'MNRD'; { Microsoft Word ) 

fMPW = 'MPS '; ( MEW ) 

fMDS = 'EDIT'; ( MDS 68000 } 


fromEFS = 0; { denotes the source file system } 
toFS e 1; { denotes the destination file system } 


TYPE 
{This data type is used to hold the File system nicknames, MC,MS,PD. } 
halfResType = packed array[1..2] of char; 


( "sw Global Variables record Yoko soon ) 
StatusRec = RECORD 
mystatus : longint; ( keeps the status bits for the translator, 
see discussion about TranData in the manual } 
myID : integer; { ID number of the STRE resource containing 
error strings } 
myfref : integer; ( The file reference number for my resource file ) 
trankind : integer; { The type of translation occurring, eg Mac to Mac} 
ftype : OSType; ( The creator name for the destination file ) 
fkind : integer; ( the offset from the MacWrite dialog button ) 
frHandle : Handle; ( handle to the source file system resource |} 
toHandle : Hand)e; ( handle to the destination file system | 
srcsize : longint; ( byte size of the source file } 
end; 
StatPtr » ^StatusRec; 
StatHndl = ^StatPtr; 
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{ set up the radio button } 

{ get the previously selected file type, this is an offset from MacWrite) 
curfkind := statrec^^.fkind: 

( get a handle to that item ) 

getDItem(user ptr,d MWradio*curfkind, itype, iHndl, iRect) ; 

.cHndl := POINTER(iHndl!; 

( turn the button to that item on } 

SetCtiValue (cHndl, 1); 

{ display the dialog box on the screen } 

showWindow (user ptr); 


repeat. 
{ wait for a click in the dialog box } 
modalDialog(NIL, item); 
( if click anywhere except OK or Cancel } 
if item in (d MWradio..d otherText] then begin 
( if clicked on document icon calculate to which radio button } 
{ it belongs. } 
if item >= d MWicon then item :» d MWradio + (item - d MWicon); 
( if the new "choice is not the same as the old choice T 
if curfkind «» (item - d MWradio) then begin 
( get a handle to the old ítem ) 
getDItem(user ptr,d MWradio-«curfkind, itype, iHndl, iRect): 
cHndl := POINTER(iHndl): 
| turn its radio button off ) 
SetCtlValue(cHndl,0); 
{ get a handle to the new item } 
getDItem(user ptr,item,itype,iHndl,iRect); 
cHndl :- POINTER(iHndl); 
{ turn its radio button on ) 
SetCtiValue (cHndl,1); 
( calculate the new offset from MacWrite } 
curfkind := item - d MWradio:; 
( if the Other radio button is not highlighted then put } 
( the apporiate creator type in the text box ) 
if curfkind « tother then begin 
case curfKind of 
tMacWrite : str := fMacWrite; 
tMSWord : str := fMSWord; 
tMPW : str :» fMPW; 
tMDS : str := fMDS; 


end; 
getDItem(user ptr,d otherText,itype,iHndl, iRect) ; 
SecIText (iHndl, str); 
end; 
end; 
end; 
until item in (d OK,d Cancel]; . 


if item = d OK then begin 

{ save the destination file type in the Global variable ) 
statrec^^.fkind := curfKind; 
getDItem(user ptr,d otherText,itype,iHndl, iRect); 
GetIText (iHndl, str); 
( Make sure that the file type is four characters long ) 
statrec^^.ftype :* ' "i 
( Take only the first four characters of the file type } 
for i :- 1 to 4 do begin 

1f length(str) >= i 

then statrec^^.ftype[i] := str[i]; 

end; 
{ Set the Active bit in the status variable } 
statRec^^.myStatus := bor(statRec^^.myStatus,trnActive); 
end; 


DisposDialog(user ptr); 
end: 
{ Return the current translator status. } 


Activate :- statRec^^.myStatus; 
end; ( Activate ) 
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unit TransExample; 


(* 
nt 
t 

* File: Example.p 


t 


* Example translator between Macintosh, ProDOS, and MS-DOS. 


© 

® 

* 

(* This translator opens up the resource fork of a Macintosh file and copies * 
* All resources of the type STR# to a text file on any of the file systems. 
If the transiation is Mac to Mac a dialog box is available to set the 
creator type of the text file (to open it just double click on it ). 

Note that this dialog box is only available when the translator is in the 
Mac to Mac menu, in the other menus it will not appear since Mac creator 
types have no meaning in the otber file systems. Also notice how this 
translator protects itself from being loaded into menus in which it has no 
usefulness. *} 


at X €* Mox t 
* + @ Rh +*+ 


INTERFACE 


USES 

(SLOAD MacLoad.L) MemTypes, QuickDraw, osIntf,toolIntf,packIntf,macPrint, script, 
{SLOAD ) AFETrans; 

( AFETrans contains all of the standard AFE data structure definitions } 


( This is the function through which AFE communicates with the translator } 
function TranStr (Message : integer; VAR TranslateData : Handle; 
Param : longint; Self : handle) : longint; 


IMPLEMENTATION 
(SR-) 


CONST 
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¥ * 

* constants for strings (for error messages) " 

* the order of these strings is the same as in Example.r * 

¥ * 

ux eee ee de ER n RR in ARERR E RAE CRT EERE EE ARERR AER AAT EER SER ES } 

str error = 1; ( “An error occurred while * } 

str creating = 2; "creating the destination file: " } 

str opensrc = 3; “opening the source file: " } 
str opendst = 4; “opening the destination file: " ) 

str getfinfo - 5; "getting information about the file: " ) 
str setfinfo = 6; "setting the file type of the destination file: * ) 

str reading = 7; "reading in the source file: " ) 
str writing = 8; "writing out the destination file: " ) 
; "Copying STR# resources." } 

str_initing = 10; { "initializing the translator " } 

str period = 11; ( ".*) 

str cant = 12; { "It cannot translate from * ) 

str to = 13; {° to” ) 

str delsrc = 14; { "deleting the original file (your translated data is in the file 

SSSAFE-TEMPSS$$): " ) 
str rendst = 15; ( "renaming the destination file (your translated data is in the 
file $$SAFE-TEMPS$$): ") 

str numstrings = 16; { "Number of STR# resources in this file: " } 
str_stringRes = 17; { "String Resource number " } 
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found := false; 
{ Search through the whole tproc family for the one that translates 
between the two character families } 
for i := 1 to tp^^.lastentry do with tp^^.tprocs(i] do begin 
if altcountry = trnpb^.trncountry then 
if (curCharFam = loCharSet) and (altCharFam = hiCharSet) then begin 
found :- true; 
entry := 1; 
leave; 
end; 
end; 
if not found then exit (GetTProc); 
( Get a handle to the tproc specified by the tproc family entry : 
tproc :- POINTER (GetResource ('tprc',tp^^.tprocs[entry]l.tprcID)):; 
( exit if the resource cannot be found ] 
if tproc = NIL then exit (GetTProc); 
{ if not currently in memory thant load it now } 
if tproc^ = NIL then loadResource (POINTER (tproc) ); 
with tpb do begin 
featureflags := band (tproc^^.flags,theflag): 
newcntry := -1; 
( these fields are reserved set to zero } 
tpRsrv(0] :- 0; 
tpRsrv(lj :» 0; 
tpRsrv[2] := 0; 
tpRsrv(3] :* 0; 
( initialize transliteration procedure ) 
verb :» transInit; 
err :9 CallTProc(tpb, tproc) ; 
if err <> noerr then begin 
tproc := NIL; 
exit (Get TProc) ; 
end; 
( the translations will be transLotoHigh ) 
verb := theverb; 
end; 
end; 
g {* This procedure send the source string to the Transliteration 
* procedure and returns the result in tpb.dstText.trPtr. The verb for 
* the translation was set in GetTProc. 
* OUTPUT : Bufsize is changed to be the size of the destination 
buffer. It is used in WriteString. 
*) 
Procedure TranslitString(VAR str : str255); 
var 
err : OSErr; 


{ if there is no tproc than just move the source buffer to the 
loBuffer buffer ) 
if tProc = NIL then begin 
blockmove (POINTER (ORD4 (8st r) *1),8buf, length (str)); 
bufsize := length (str); 
end 


else begin 

tpb.srcText.trLen := lengthistr); 

{ The first element of a string is its size, since we do not 
want to translate this character we set the buffer to the 
next one. } 

tpb.srcText.trPtr := POINTER (ORD4 (Gstr)*1); 

tpb.srcText.trFont := 0; 

tpb.dstText.trLen := 512; 

tpb.dstText.trPtr :- übuf; 

tpb.dstText.trFont := 0; 

(if the tproc is not in memory than load 1t ) 

if tproc^ = NIL then loadResource (POINTER (tproc) ); 

err :* CallTProc(tpb,tProc); 

bufsize := tpb.dstText.trLen; 

end; 

end; 
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{ Listing of all the functions in this unit } 

Function Activate(statRec ; statHndl; trnPB : trnPtr) : longint; Forward; 

Function CopyFile(srcref,dstref : integer; statRec : statHndl; trnPB : trnPtr) 
: OSErr; Forward; 

Function DoAppear(trnpb : trnptr; statRec : statHndl) : longint; Forward; 

Function  DoFileConvert(statRec : statHndl; trnPB : trnPtr) : longint; Forward; 

Function DoFinish(VAR translateData : handle) : OSErr; Forward; 

Function Doinit (VAR translateData,self : handle; trnpb : trnPtr) 
: longint:; Forward; 

unction DoName(statRec : statHndl; trnPB : trnPtr) : longint; Forward: 

Function FileIO(ff,fs : integer; pb : HParmBlkPtr; statrec : StatHndi; trnPB : trnPtr) 
: OSErr; Forward; 

function FileOp(ff,fs : integer; pb : HParmBlkPtr; statrec : StatHndl: trnPB : trnPtr) 
: OSErr; Forward; 

Function GetstrSize(fref : integer) : longint; Forward; 

Function RecogFile(statRec : statHndl; trnPB : trnPtr) : longint; Forward; 

Procedure ReportErr(err,doing : integer; statRec : statHndl: trnPB : trnPtr); Forward; 


(sts ORO ein Activate RE ARATE AA REET HECKER ACE RE E Eid 


Called when translator receives a trn Activate. * 
ACTIVATE indicates that the user wishes to check this menu item. The * 
routine does whatever it wants (usually just setting the appropriate bit * 
in the flags, but it could be as complicated as a dialog box prompting * 
the user for options), and then returns the new status flag as the * 
function result. In this case Activate only puts up a dialog box if it is* 
being activated in the Mac to Mac menu; otherwise it just updates the * 
active bit in the status variable. * 
Notice how the dialog box is only activated for the Mac to Mac trans- * 
lation. For the other translation the we just set the active bit. w 
A CR REE E RRR EARNEST TNR EEE EE TEE RENEE ER SER EAE NSS ) 


Function Activate(statRec : statHndl; trnPB : trnPtr) : longint: 


* 2 X X X X* X* * X o* 


var 
user ptr : dialogPtr; 
cHndl : Controlhandle; 
itype : integer; { type of item in the dialog box,see Inside Mac 
vol I for details) 
iHndl : handle; { a handle to an item } 
irect : rect; { the display rectangle for the item ) 
4 : integer; 


str : str255; 
item : integer; 
curfkind : integer; ( the current destination file type } 
oldres : integer; 
begin 
( if the translation is to prodos or msdos ) 
1f statrec^^.tranKind » tMCMC 
then statRec^^.mystatus := bor (trnActive, statRec^^.mystatus) 
else if statrec^^.tranKind = tMCMC then begin 
( 1f the translation is Mac to Mac than get the option dialog box ) 
oldres := curResFile; { in case another resource file is being used ) 
useResFile(statRec^^.myFref); 
user ptr :- getNewDialog(statRec^^.myID,nil,POINTER(-1)); 
useResPile(oldres); ( restore the old res file } 


( set up the file type ! 
str := ‘ "3 
{ check that the file type only consists of printable ascii characters } 
for i :- 1 to 4 do begin 

if statRec^^.ftype(1] in [' '..'-"'] 

then str[i] :- statRec^^.ftype[i]:; 

end; 
getDItem(user ptr,d otherText,itype,iHndl, iRect) ; 
setIText (iHndl, str); 
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(* This procedure writes to the destination file a line stating the 
* string resource ID number 
*) 
Procedure HeaderString(s,theID,numentries : integer; theName : str255); 
var 
oldres : integer; 
str : str255; 
begin 
oldres :* CurResFile; 
useResFile(statRec^^.myfref): 
( Insert a blank line ) 
WriteString('',true); 
{ Write the string ‘String Resource Number ' } 
GetIndString(str,statrec^^.myID,str stringRes); 
WriteStrinq (str, false); 
{ convert the resource ID number to a string } 
NumToSt ring (theID, str); 
WriteString(str, true}; 
{ make the old resource the current one } 
useResF ile {foldres) ; 
end; 


(* This procedure writes to the destination file one of the strings in 
*a STR# resource. It is called from the main body of CopyFile 
v) 
Procedure EntryString(str : str255; n : integer); 
var 
oldres : integer; 
str2 : str255; 
begin 
writeString(str,true); 
end; 


begin ( Main body of CopyFile ) 

( save the current resource file to restore later ) 

oldres := CurResFile: 

useResFile (srcref):; 

{ get the number of STR# resources } 

numstr := count lResources ('STR#'); 

( Write the number of STR# resources to the destination file } 
Header (numstr); 

for s := 1 to numstr do begin 

{ get the sth resource from the source file } 

hstr := GetlIndResource ('STRÉ', 3); 

if hstr = NIL then leave; 

GetResInfo(hstr,theID, theType, theName) ; 

( make numptr point to the same place as the master pointer 
of the STR# resource. Since numptr is of a different type we 
use Pointer to avoid type conflicts. ) 

numptr :» POINTER (hstr^); 

( The first value in a STRé resource is the number of strings in 
the resource (an integer value). Since numptr is a “integer, it 
is pointing to this value ) 

numentries := numptr^; 

Headerstring(s,theID,numentries,theName); 

{ get each string in the resource and write it to che destination 
file ) 

for n :- 1 to numentries do begin 
GetIndString(str,theID,n):; 

EntryStríng (str,n); 
end; 

end; 

( if we have been using a tproc tell it that we have finished the 
translation ) 
if tproc © NIL then begin 

tpb.verb :- transdone: 

if tproc^ = NIL then loadresource (POINTER (tproc) ); 

if CallTProc(tpb,tproc) <> noerr then ; 

end: 

useResF ile (oldres) ; 
CopyFile := noerr; 
end; { CopyFile } 
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{* This is the function that actually does the translation of the STR# re- * 
* source to a text file. 
INPUT : srcref,dstref - file reference numbers for the source and destination 
file. 
datasize - the size of the source file 
statRec - the Global variable record. 
RESULT: The sucess or failure of the translation. 
USED by : DoFileConvert 
* Notice its use of tprocs to transliterate between the various character 
* sets used by the different file systems. Also notice that whenever tprocs 
* are called we make sure it is loaded in memory by using LoadResource, just 
* because we have a handle to it does not mean it resides currently in 
* memory because it is a purgeable resource. 
*} 
Function CopyFile(srcref,dstref : integer; statRec : statHndl; trnPB : trnPtr) 
var 
oldres : integer; 
numstr,numentries : integer; 
$,n : integer; 
hstr : handle; 
numptr : ^integer; 
str : str255; 
theID : integer; 
theType : ResType; 
theName : str255; 
datasize : longint; 
buf : array(0..511] of signedbyte: 
bufsize : integer; 
pb : ParamBlockRec; 
tpb : transPB; 
tproc : hdrHndl: 


(* This procedure finds the desired TProc for tbe transliteration 
* between the Mac and one of the other file systems and intializes it 
*) . 
Procedure Get TProc; 
var 
tp : tprfHndl: 
found : boolean; 
entry : integer; 
1 : integer; 
loCharSet,hiCharSet : integer; 
theverb : integer; 
theflag : integer; 
err : OSErr; 
begin 
tproc := NIL; 
{ One doesn't need a Tproc if the translation involves only one 
computer type } 
if statrec^^.trankind = tMCMC then exit (GetTProc) ; 
( get a handle to the Tproc family for the given source country, 
if more than one trpf is available the user chooses which one to 
use from the country menu provided by AFE. } 
tp :- POINTER (getRescurce('tprf',trnpb^.trncountry]]:; 
if tp = NIL then exit (GetTProc) ; 
case statrec^^.tranKind of 
tMCPD : begin 
loCharSet := cfMacintosh; 
hiCharSet := cfASCIT; 
theverb := transLotoHi; 
theflag := trNonOnetoOne; 
end; 

tMCMS : begin 
loCharSet :» cfMacintosh; 
hiCharSet := cfIBMPC; 
theverb := transLotoHi; 
theflag :* trNonOnetoOne; 
end; 

end; 
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: OSErr; 


{ if another error occurred then do not translate } 
if err © noerr then err :* fBsyErr 
else tempfile := true; 


end 
( if the destination is not the same as the source then delete 


the current file and create a new destination file } 
else begin 
loNamePtr := @tostr: 
ioFVersNum := 0; 
err2 := FileOp(FFDelete,toFS,8pb,statrec,trnpb); 
if err2 = noerr then begin 
ioNamePtr :- 8Rtostr: 
pb.ioFVersNum := 0; 
err := FileOp (FFCreate, toFS, @pb, statrec,trnpb) ; 
end; 
end; 
end; 
{ if the last operation was successful then the destination file 
was created } 
if err = noerr 
then dstcreated := true 
else reportErr (err, str_creating, statRec, trmPB) ; 


end; 


( 1f a Mac to Mac translation } 
if statRec^^.trankind  tMCMC then begin 
(* Note: before doing a SetFInfo it is a good idea make sure that there is * 
* valid information in all param block fields so do a GetFinfo first mt 
if err = noerr then with catpb do begin 
loNamaPtr := ftostr; 
ioFDirIndex := 0; 
err := FileOp(FFGetFInfo,toFS, écatpb, statrec, trnpb) ; 
{ If the destination gives a bad param block try the source } 
if err © noerr then begin 
loNamePtr := @frStr; 
ioFVersNum := 0; 
err := FileOp(FFGetFInfo,fromES,8catpb, statrec,trnpb):; 
err :» noerr; 
end; 
end; 
{ Set the destination file type and creator } 
if err = noerr then with catpb do begin 
ioNamsPtr := @tostr; 
loflFndrInfo.fdtype := ‘TEXT’; 
loflFndrInfo.fdcreator := statrec^^.ftype: 
err := FileOp(FFSetPInfo,toFS, Rcatpb, stat rec, trnpb) ; 
if err © noerr then reportErr(err,str setfinfo,statRec, trnPB) ; 
err :™ noerr; 
end; 
end; 
{ For all file systems open the destination ) 
if err = noerr then with pb do begin 
ioNamePtr := @tostr; 
if statrec^^.tranKind = tMCPD 
then ioPermssn := 0 
else ioPermssn :- fsWrPerm: 
loMisc := NIL; 
err : FileOp(FFOpen,toFS,Bpb,statrec,trnpb); 
if err = noerr then begin 
dstopened :» true; 
dstref := ioRefNum; 
end 
else reportErr(err,str opendst, statRec,trnPB); 
end; 
( check to see if the file is already opened ) 
if err = noerr then with catpb do begin 
ioNamePtr :- @frstr; 
ioFVersNum :* 0; 
ioFDirIndex :- 0; 
err :- FileOp(FFGetFInfo,fromFS, ü8catpb, statrec,trnpb); 
if err <> noerr then reportErr (err,str getfinfo, statRec,trnPB); 
end; 
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(* This procedure writes out a string to the destination file and adds 
* a carriage return if cr is true. It assumes that the string is 
* already pointed to by pb.ioBuffer using the assignment 
* pb.ioBuffer := @Buf. It also assumes that GetfTProc has already been 
* called to get the required TProc. 
"E 
Procedure WriteString(str : str255; cr : boolean); 
var 
pct : integer; 
err : OSErI; 


( Use the tprocs to transliterate between character sets ) 


TranslitString (str); 
pb.ioReqCount := bufsize:; 
err := FileIO(FFWrite,tofs,&8pb, stat rec, tzmpb) ; 
( add the carriage return to the destination file ! 
if cr and (err = noerr) then begin 
puf(0] :- 13; (carriage return) 
bufsize := 1; 
{ if translating to an MSDOS disk a line feed is also needed to 
start a new line. } 
if statrec^^.tranKind = tMCMS then begin 
buf(1] := 10; { line feed ! 
bufsize := 2; 
end; 
pb.ioReqCcunt := bufsize; 
err :@ FilelO(FFWrite,tofs,üpb, statrec,trnpb); 
end; 
( report any error that occurred while writing to the destination } 
if err © noerr then begin 
reporterr(err,str writing, statrec,trnpb): 
CopyFile :* err; 
useResFile(oldres); 
exit (copyFile) 
end; 
( compute how mich of the translation has been completed for 
display in the status window } 
datasize :e datasize*length (str); 
:- datasize * 100 div statrec^^.srcSize; 
if pct < 0 then pet := 0 
else if pct » 100 then pct :* 100; 
( if user clicks on cancel } 
if not CallStat('',pct,l,trnpb^.trnStatProc) then begin 
CopyFile := trnCancel; 
useResF1le(oldres); 
exit (copyFile); 
end; 
end; 


{* This procedure writes out the first line of the destination file 
* it tells how many strings there are to translate } 
Procedure Header (numstr : integer); 


oldres : integer; 
str : str255; 
begin 
datasize := 0; 
Get TP roc; 
pb.ioCompletion :* NIL; 
pb.ioRefNum := dstref; 
pb.ioBuffer := @buf; 
pb.ioPosMode := fsAtMark; 
oldres := CurResFile; 
useResF1ile(statRec^^.myfref); 
GetIndString (str, statrec”* .myID, str_numst rings) ; 
WriteString (str, false); 
{ convert the count of STR# resources to a string } 
NumfoString(numstr, str) ; 
WriteString(str, true); 
useResF ile (oldres) ; 
end; 
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* Called when transitor receives an trn FINIS. * 
* DoFinish cleans up any global variables that might have been allocated. * 
* ALWAYS returns NoErr. It is only called when execution of AFE is x 
* terminated (1e. you hit quit ). * 
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Function DoFinish(VAR translateData : handle) : OSErr: 
begin 
DoFinish :* noErr; 
if translateData <> NIL then disposHandle (translateData); 
translateData := NIL; 
end; 


{PROT e TAA AR ELAR em dni fce AREA AAA EE DoInit IbbidAbhb$dbbihbibl&sdéádiéshshdhbhl 


* Called whenever a translator receives a trn INIT message. This happens 
wben translators are imported to other menus as well as at startup. 
DoInit initializes the variables we need. It allocates a relocatable 
block of memory and puts the handle in translateData. It determines the 
source and dest file system and sets up the default parameters. It 
returns noErr if all goes well, and a negative result otherwise. 
D IITLILILILLERRIIDIRDIDRRRRRPERRRRERIRDIRDRDRSRRRRRRRSRSRRRRSREESLSEEEAERAEL AE LE S ld 
Function DoInit(VAR translateData,self : handle; trnpb : trnPtr) : longint; 
var 
theID : integer; theType : restype; namefr,nameto,myname : str255; 
str : str255; 
dstnick,srcnick : halfResType; 
err : OSErr; 
statRec : StatHndl; 
kind : integer; 
srcHandle,dstHandle : handle; 
len : integer; 
thefref : integer; 


* 
* 
* 
* 
* 


+ ox xk *  & 


(* get handles of source and dest file systems 
* Note: GetResource returns NoErr even if it does not find the 
* resource. This is why one must check for NIL handles as well as 
* ResError.) 
srcHandle := GetResource (foreignFS,trnpb^.trnfrID); 
err := ResError; 
if (err = noErr) and (srcHandle = NIL) then err := resNotFound; 
if err » noerr then begin 
dstHandle := GetResource (foreignFS,trnpb^.trntoID); 
err := ResError; 
if (err = noErr) and (dstHandle = NIL) then err := resNotFound; 
end; 


(* get nickname of source file system = The last two characters of 
* the file system name; MC, MS, PD. ) 
if err = noerr then begin 
GetResInfo (srcHandle, theID, theType, namefr); 
err :- ResError; 
end; 
if err = naErr then begin 
len :* length(namefr): 
if len <= 2 then err := bdNamErr:; 
end: 
if err  noErr then begin 
srcnick[1] := namefr[(len-1]; srcnick[2] := namefr(len]: 
1f (srcnick <> 'PD') and (srcnick <> 'MS') and (srcníick <> 'MC') 
then err := extFSErr; 
end; 


(* get nickname of destination file system *) 
if err = noerr then begin 
GetResInfo (dstHandle, theID, theType, nameto); 
err := ResError; 
end; 
if err = noErr then begin 
len := length (nameto); 
if len <= 2 then err :© bdNamErr; 
end; 
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* DoAppear is cailed in response to à trn APPEAR message which occurs when 
a new disk has been selected which has caused this routine to appear in 
its menu. We do not change appearance in the menu, except to clear any 
gray bits that may have been set. Returns NoErr as function result. 
Same functions may use this procedureto define some global data 
(such as source or destination FS, etc ). 
Notice how the grey bit is turned off. First we create this bit value 
with all the bits except for the grey bit on (-1 = SFFFFFFFF) Then we 
bit and this with the current status, any high bits in the current 
status remain high and none that are not are activated. This is called 
masking, and is the most effecient method for changing individual status 
bits. 
ae ORTH IIIS ISERIES IDS NOI nnn HOO RH E) 

Function DoAppear(trnpb : trnptr; statRec : statHndl) : longint; 

begin 

statRec**.myStatus := band (statRec^^ .myStatus, -1-trnGray); 

DoAppear := noErr; 

end: ( DoAppear ) 


@ +++ *@ &@ X @ * & SH 
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( tociens eedem qoe eee DoF ileConvert "TIIRISRRIIIRAILRERRARRERRRARRAREER 
* Called when the translator receives a trn FILE. Result » Accept,unAccept, 2 
* or Cancel. * 
* This function creates the necessary files for the translation to occur. * 
* The actual translation is done by another function CopyFile. * 
x Notice the care used in regards to duplicate file names, particularly the * 
* creation of an intermediate file when copying in place (ie replacing the * 
* source with the destination file). s 
Xx Y ae OR FUR ICON CORE RC CRI EER EREEE RETR EE EERE E EN TIES | 
Function DoPileConvert(statRec : statHndl; trnPB : trnPtr) : longint; 
var 
err,err2 : OSErr; 
srcopened, dstcreated, dstopened, tempfile : boolean; 
pb : HParamBlockRec; 
pbold,pbnew : WDPBRec; 
catpb : CInfoPBRac; 
srcref,dstref : integer; 
frstr,tostr : str255; 
str : str255; 
begin 
DoFileConvert :*9 unaccept; 
( Note how we always use the same recognize for trn File and trn Recognize 
if RecogFile(statRec,trnPB) = accept then begin 
DoFileConvert := accept; 
srcopened := false; 
dstcreated := false; 
dstopened :- false; 
tempfile :» false; 
tostr := trnPB^.trnnames^^.names(1]; ( source file name } 
frstr :- trnPB^.trnnames^^.names[0]; ( destination file name } 
err :- noerr; 
( create the destination file ] 
if err = noerr then with pb do begin 
ioNamePtr := @tostr; 
pb.ioFVersNum := 0; 
err := FileOp(FFCreate,toFS, @pb, stat rec, trnpb) ; 
( if the file already exists } 
if err = dupfNErr then begin 
( check to see if it is the source file } 
if (trnpb^.trnfrID = trnpb^.trntoID) 
and (trnpb^.trnfrVRef = trnpb^.trntoVRef) 
and (trnpb^.trnfrpar = trnpb^.trntopar) 
and (tostr = frstr) then begin 
( if it is then create a temporary file to hold the tran- 


slation ) 
tostr := '$$S8FE-TEMPSSS'; 
repeat 


( increment the fourth letter by one until we get } 
( a unique name for the temporary file } 

tostr(4] := CHR(ORD(tostr[4]) *1); 

err := FileOp(FFCreate, toFS, @pb, stat rec, t rnpb) ; 
until err <> dupfNErr: 


C-10 Appendix C: An Example of a Translator 


if err © noerr then begin 
GetIndString(str,theID,str error); 
CallErrLog (str, false, false,trnpb^.trnlogproc); 
GetIndString(str,theID,str initing); 
CallLog(str,false,false,trnPB^.trnlogproc); 
CallLog (myname, false, false,trnPB^.trnlogproc); 
GetIndString(str,theID,str period); 
CallLog(str,true, false, trnPB*.trnlogproc) ; 
{ If translator is not in a valid menu } 
if err = extFSerr then begin 
GetIndString(str,theID, str cant): 
CallLog(str,false,false,trnPB^.trnlogproc): 
CallLog (copy (namefr, 1, length (namefr) -2), false, false, trnPB^.trniogproc); 
GetIndString (str,theID,str to); 
CallLog(str,false,false,trnPB^.trnlogproc): 
CallLog (copy (nameto, 1, length (namato) -2), false, false,trnPB^.trrlogproc); 
GaetIndStríng(str,theID,str period): 
CallLog(str,true, false, trnPB* .crnlogproc) ; 
end; 
end; 


DoInit := err; 
end; ( DoInit } 


{FERRARA ERA AR ARTE IER ERR DoName RERMCEALAAACAATKAREKAKKKKAERATLREEKEKE 


* Called when the translator receives a trn NEWNAME message 
trn NEWNAME is passed a trnPTR in PARAM. It should check the fiie 
specified as the source and return either NOERR or UNACCEPT as the 
function result, depending on whether the file matches the criteria for 
acceptance by this routine (it can skip checking for acceptance if the 
trnTESTED field is true -- in that case, the trnACCEPTED fleid indicates 
whether this file was previously accepted). If acceptable, then 
trn NEWNAME should return a suggested new name for the destination file, 
and set the field trnNAMES.NAMECNT to 1. On those occasions when more 
than one destination fíle vill be produced, the name handle should be 
expanded and trnNAMES.NAMECNT should be increased appropriately. 
fetiefinietfieesietiteminemttm f fcm fete ddnde fece de) 
Function DoName(statRec : statHndl; trnPB : trnPtr) : longint; 
var 

temp : longint; 

pb : HParamBlockRec; 
err : OSErr; 


str255; 
begin 
DoName :* unaccept; 
if RecogFile(statRec,trnPB) = accept then begin 
str :» trnpb*.trnNames**.names (0); 
trnpb^.trnNames^^.NameCnt := 1; 
pb.ioNamsPtr := @str; 
pb.ioDirID := trnpb^.trnToPar; 
pb.loVRefNum :9 trnPb^.trnToVRef; 
err :- FileOp(FFMakeFNamm,toFS, pb, stat rec, trnpb) ; 
if err = noerr then begin 
trnpb^.trnNames^^.names[1] := str; 
DoName : accept; 
end; 
end; 


end; ( DoName } 


* * X * X oe * 9 X ox 
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if (err = noerr) and (band (catpb.ioFlAttrib,$04) = 9) then with pb do begin 
phold.ioCompletion := NIL; 
poold.ioNamePtr := NIL; 
err :» PBHGetVol (@pbold, false); 
if err = noerr then with pbnew do begin 
locompletion :* NIL; 
ioNamePtr := NIL; 
ioVRefNum := trnpb^.trnfrvref; 
ioWDDirID := trnpb^.trnfrpar; 
err := PBüSetVol(8pbnew, false); 
end; 
if err = noerr then begin 
srcref := OpenResFile(trnpb^.trnNames^^.names[0]); 
err :» PBHSetVol(8pbold,faise); 
end; 
( if the resource fork of the source could not be opened tben exit j 
if (err = noerr) and (srcref <= 0) then err := fnferr; 
if err = noerr then begin 
srcopened := true; 
end 
else reportErr(err,str opendst,statRec, trnPB) ; 
end 
else if err = noerr then srcRef := catpb.iafRefNum; 
( If opened destination get size of source strings, this value is saved in 
statrec^^.srcsize after opening the source file *} 
tf err = noerr then with catpb do begin 
statrec**.sresize := GetStrSize (srcref) ; 
end; 


{ If no errors so far then translate the file } 

Get IndString (str, statrec** .myID, str_copying) ; 

if not Callstat (str, 0,1,trnpb*.trnStatProc) then err := trnCancsl; 
if err = noerr then err := copyFile (srcref,dstref, statrec,trnpb); 
if not CallStat('',100,1,trnpb^.trnStatProc) then err := trnCancel; 


( Close the files and erase any temporary files } 
if srcopened then with pb do begin 
CloseResFile(srcref):; 
if dstopened then with pb do begin 
"ioRefNum := dstref; 
err2 := FileIO(FFClose,tofs, @pb, statrec, trnpb) ; 
end; 
( If an error occurred during translation than delete the destination 
file, it is not valid } 
if (err © noerr) and dstcreated then with pb do begin 
ioNammPtr := @tostr; 
loFVersNum :*- 0; 
err2 := FileOp(FFDelete,toFS,8pb,statrec,trnpb); 
end; 
( 1f a translation in place was completed then delete the source and 
rename the destination with the source name } 
if (err = noerr) and tempfile then with pb do begin 
ioNamePtr := @frstr; 
iofVersNum :- 0; 
err2 := FileOp(FFDelete, toFS, (pb, stat. rec, crnpb) ; 
if err2 © noerr then reportErr(err2,str delsrc, statRec, trnPB) ; 
if err2 = noerr then begin 
ioNamePtr := @tostr; 
ioFVersNum := 0; 
loMisc :- @frstr; 
err2 :- FileOp(FFRename,toFS, pb, statrec,trnpb); 
if err2 © noerr then reportErr(err2,str rendst,statRec,trnPB); 
end; 
end; 
if err = trncancel then DoFileConvert := trnCancel; 
end; 
end; { DoFileConvert } 
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* Called when trasniator receives trn Recognize. 
* It is also called by DoName and DoFileConvert. 


y 5$ € €» X € X 


accept the file. 
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Function Recogfile(statRec : statHndl; trnPB : trnPtr) 
var 
err : OSErr; 
pb : HParamBlockRec; 
pbnew,pbold : WDPBRec; 
temp : OSType: 
size, readsize : longint; 
fref, num : integer; 
srcopened : boolean; 
oldres : integer; 
begin 
(* check if the file's already been tested *) 
RecogFile := unaccept; 
if trnPB^.trnTested then begin 
if trnPB*.trnAccepted then RecogFile := accept; 
exit (RecogFiie); 
end; 


(* check whether we have a rescurce fork or no *) 
pb.ioNamePtr :- ütrnpb^.trnNames^^.names(0]; 
pb.ioFDirIndex := 0; 

err := PileOp(FFGetFInfo,fromFS, pb, statrec,trnpb); 


RecogFile is passed a trnPTR and status record. It should check the file* 
specified as the source and return either ACCEPT or UNACCEPT as the 
function result, depending on whether the file matches the criteria for 
acceptance by this routine. Notice how we do not log errors during that 
may occur in this function. We only want to know if this transiator can 
translate this file or not, if it can't for any reason then we do not 


: longint: 


if err © noerr then exit(RecogFile); ( don't log errors during recognition } 


if pb.icFlRPyLen = 0 then exit (RecogFile); 


srcopaned :- false; 


if band(pb.ioFlAttrib,$04) = 0 then begin ( if already opened, don't reopen } 


(* now wa have to check things out via the resource manager *) 
(* first: set up the volume because the resource manager doesn't allow 


AND directory specification *) 
pbold.ioCompletion :* NIL; 
pbold.ioNamePtr := NIL; 
err :«e PBHGet Vol (@pbold, false); 
if err © noerr then exit (RecogFile) ; 


ioVRefNum :- trnpb^.trnfrvref; 

loWDDirID :» trnpb^.trnfrpar:; 

err := PRHSet Vol (@pbnew, false); 

if err © noerr then exit (RecogFile); 

end; 
fref := OpenResF1le(trnpb^.trnNames^^.names[01); 
err := PBHSetVol (@pbold, false); 


{ if the resource fork of the source could not be opened then exit ) 


if fref <= 0 then exit (RecogFíle); 
srcopened :* true; 
end 
else fref := pb.ioFRefNum; 
oldres := CurResFile; 
useResFile(fref) ; 
num := count lResources({'STR#'); 
useResFile (oldres) ; 
if mum > 0 
then RecogFile := accept; 
if srcopened then begin 
CloseResFile(fref) ; 
end; 


end; { Recogfile } 


volume 
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if err = noErr then begin 
dstnick(1) :- nameto(len-1]; dstnick(2] := namato(len]; 
if (dstnick <> 'PD') and (dstnick <> 'MS') and (dstnick <> 'MC') 
then err ;- extFSErr; 
end: 


(* get information about translator. Keeping the file reference number 
* allows one to switch the resource file in use to one's own if it is 
* not the current one. 
*} 
if err = noerr then begin 

getResinfo (self, theID, thetype, myname) ; 

err := ResError; 

end; 
if err » noerr then begin 

theFRaf := homeResFIle(self); 

err ;* ResError; 

end; 


(* determine kind of translation. This translator only supports tran- 
* slation from the Macintosh file system. If we are not in one of these 
* manus then generate an error. 

Li 
} 

if err = noErr then begin 
if (srenick='MC') and (dstnick = 'MC') then kind := tMCMC 
else if (srcnicke'MC') and (dstnick = 'PD') then kind :- tMCPD 
else if (srenick='"MC') and (dstnick = 'MS') then kind := tMCMS 
else err := extFSerr; 
end; 


(* get global data space. Why do we make statrec a pointer to handle can 
you even do this?!? *} | 
if err = noErr then begin 

translateData := NewHandle (sizeof (statusRec) ) ; 

statrec := POINTER(translateData); 

err := Mem£rror; 

end; 


(* set up default settings *) 
tf err = noErr then with statRec^^ do begin 
( Check menu item (make it active) and set the About bit } 
myStatus := trnActive + trnAbout; 
( the ID number of the translator resource ] 
myID :- theID; 
( the file reference number of the translator file ) 
myFref :- theFref; 
( the type of translation (Mac to Mac, etc.) ) 
trankind := kind; 
{ default file type is MacWrite ) 
ftype := 'MACA'; 
( default translation is into a MacWrite file } 
fkind := tMacWrite; 
{ Handles to the source and destination file system (resources). } 
frHandle := srcHandle; 
toHandle := dstHandle; 
end; 
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trn_Appear : begin 
TranStr := DaAppear (trnpb, statRec) ; 
end; , 


trm Disappear : begin 
{* trn DISAPPEAR cleans up any global variables that might have 
* been allocated by trn APPEAR.  ALWAYS returns NoErr. 
=} 
TranStr := noerr; 
end; 


trn_Get : begin 
(* crn GET returns the current status of this routine as the 
* function result. 
E 
TranStr :- statRec^^.myStatus; 
end; 


trn Set : begin 
(* trn SET sets the status flag of this routine using the 
* value in PARAM. The new status flag is returned as the 
* function result. 
* 
statRec** .myStatus := param; 

TranStr :* param; 


end; 

trn Active : begin 
TranStr :» Activate (statRec,trmPB); 
end: 


trn Inactive : begin 

(* trn INACTIVE indicates that the user vishes to UNcheck this 
* menu item. The routine just clears the active bit in the 

* flags, and then returns the new status flag as the 

* function result. 

*} 

sta ^^.myStatus :» band(statRec^^.myStatus,-1-trnActive); 
TranStr := statRec^^.myStatus; 

end; 


trn Recognize : begin 
TranStr := RecogFile(statRec,trnpb):; 
end; 


trn NewName : begin 
TranStr :*» DoName(statRec,trnpb); 
end; 


trn File : begin 

trn FILE is passed a trnPTR in PARAM. It should check 

the file specified as the source and return either NOERR 

or UNACCEPT as the function result, depending on whether 
the file matches the criteria for acceptance by this 
routine. If acceptable, then trn FILE should do the actual 
translations, using the name (or possibly names) specified 
in the name handle. Any errors encountered during translations 
should be reported to the user log. Periodically, the 
status procedure should be called with a (possibly empty) 
status message and a number between 0 and 100 indicating 
the percentage complete. This routine will return TRUE 
most of the time, but can return FALSE if the user has 
pressed the CANCEL button on the status panel. Because the 
user can press CANCEL, it is requested that trn FILE call 
the status procedure as often as necessary to achieve some 
measure of reasonable feedback. 


p 
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x 
TranStr := DoFileConvert (statRec, trnpb); 
end; 
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* This is a utility function that does the repetitive actions for 
* FFREAD, FFWRITE, and FFCLOSE. The Calling procedure provides: 


* Called by CopyFile, DoFileConvert 
* ioRefNum 

x ioposModet, ioposOffsett 

* ioReqCountt, ioBu 

2 

* t for READ and WRITE only 

* 


* 

* 

® 

"v 

* 

ffer t s 
* 

* 

T 
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RE EEA AAA AAAREEKRAEATEAAKEAEERAH "TIITTPIIILRASRARSLRAARSRERRRRIRARRARRARSRASRS 


Function FileIO(ff,fs : 


integer; pb : HParmBlkPtr; statrec : StatHndl; 


trnPB : trnPtr) : OSErr; 


Var 
err : OSErr; 
begin 


pb^.ioCompletion := NIL; 


err := NOErr; 
if fs = from's 


then err := CallFS(ff,trnpb^.trnfrData, POINTER (pb), false, statrec^^.frHandle) 
else err := CallFS(ff,trnpb^.trntoData, POINTER (pb), false, statrec^^.toHandle); 


FileIO :- err; 
end; { FileIO } 


(detecte dee JORCICR CIC ROICIOROIORCE ORIGEN FileOp ITITIZIIDILLIADRRRRRRRSARSRARÉREAESAS A Rl 


* Called by DoPileConvert, DoFileName, RecogFile s 


*ox x €* & * * 


every one of the calls. 


for FFOPEN, FFGETFINFO, FFGETCATINFO, FFSETCATINFO, FFSETFINFO, FFRENAME, * 
FFDELETE, FFCREATE, FFGETXCATINFO, FFSETXCATINEO. FFMAKEFNAME * 
Calling procedure provides (in the pb variable): * 
ioMisc,ioPermssn,ioNamePtr ~~ FFOPEN * 

This function provides the part of the CallFS function that does not * 
change for the calls listed above. It eliminates having to repeat it for * 
* 


awudku did a ex doit eddie dee doe demde eine RARE nie nie eem m) 


Function FileOp(ff,fs : 


integer; pb : HParmBlkPtr; statrec : StatHndl; trnPB 


( ff = file system command, fs = source or destination file } 


var 
err : OSErr; 


begin 

with pb^ do begin 
ioCompletion := NIL; 
if fs = fromES then 


begin 


ioVRefNum := trnpb^.trnfrVRef; 


ioDirID := trnpb^ 


err :9 CallFS(ff, trnpb*.trnfrData, POINTER (pb), false, statrec^^.frHandle); 


end 


.trnfrPar; 


else begin ( perfrom operation on the source file } 
ioVRefNum := trnpb^.trntoVRef; 


ioDirID := trnpb^ 


err := CallFS(ff,trnpb^.trntoData, POINTER (pb), false, statrec^^.toHandle); 


end; 
end; 
FileOp := err; 
end; ( FileOp } 


Function GetStrSize(fref 

var 

oldres : integer; 

size : longint; 

h : handle; 

numstr,s : integer; 
begin 
oldres := curResFile; 
useResFile(fref):; 
setResload (false); 


.LrntoPar; 


: integer) : longint; 


numstr := countlResources (‘STR#') ; 


size := 0; 


for s := 1 to numstr do begin 
h :* GetlindRescurce('STR#',s); 
size := size + MaxSizeRsrc(h); 


end; 
setResLoad (true) ; 
useResF ile {(oldres} ; 
GetStrSize := size; 
end; 
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trnPtr) 


OSErr 


* 
, 


trn SetSettings : begin 


With this message, Apple File Exch is passing a handle filled 
with data that indicates a default setting. Apple File Exchange 
allows the user to save and restore default settings 
("*preferences", if you will) so that the user can launch 

the program and have each translation be in a state that 

they are familiar with. Apple File Exch will dispose of this 
handle later (do not do so yourself). If this call is 

not supported, return NIL or some (negative) error code. 


oo, 
** ee et » » *! 


*j 
n := POINTER (param) ; 
{ If for some reason AFE does not send a pointer to the correct 
data then do not change the current set up } 
if GetHandleSizeth) <> sizeof (statusRec) then TranStr := 0 
else with statrec^^ do begin 
statrec2 := POINTER (h):; 
mystatus :- statrec2^^.mystatus; 
ftype := statrec2^^.ftype: 
fkind := statrec2^^.fkind; 
end; 
end; 
end; 


hunlock (self); 
hpurge (self): 


end; 


end. 
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Called whenever an error occurs that must be reported to the user log, le * 
it is used by almost all of the procedures. * 
Notice how part of the error message is reported using resources stored 
in the AFE resource fork (for err «0 and »-85). AFE includes some stan- 
dard strings for these errors, check them out with ResEdit to see if they 
fit in your error messages as well. They are in the STR# ID2150 resource 
dk we NC dd A Fe qe d CR e Ho RR RO RR RR T de dede dde ed in Re HR LS TOI OR ION CECI ER ) 
Procedure ReportErr(err,doing : integer; statRec : statHndl; trnPB : trnPtr); 
( err = error code (usually a File manager code, 

doing the action attempted that caused the error, one of the str. 

constants declared at the top of this unit ] 
var 

Str : str255; 

oldres : integer; 
begin 
( save the AFE file ref number of the AFE resource file | 
oldres := curResFile: 
( use the translator resource file } 
useResFile(statRec^^.myFRef): 
GetIndString(str,statrec^^.myID,str error): 
CallErrLog(str,false,true,trnPB^.trnlogproc); 
GetIndString(str,statrec^^.myID,doíng); 
CallErrLog (str, false, true, trnPB^.trnlogproc); 
useResF tle (cldres): 
( if appropriate use the error string from the AFE resource STR#150 ) 
if (err « 0) and (err > -85) 

then GetIndString(str,150, err) 

else GetIndString(str,150,5); 
CallErrLog (str, true, true,trnpb^.trnlogproc); 
end: { ReportErrLog } 


* 4+ * X @ X 
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* This is tbe function that provides the interaction between AFE and the * 
+ translator. It ALWAYS has the SAME number and types of parameters. * 
* INPUT : Message - this integer describes the opertation requested by * 
* AFE for a complete listing of these operations see the * 
* constants under the "Conversion Routine Commands" heading * 
& TranslateData - this is either the default settings for this * 
* translator, or a handle to soma global data the translator * 
* has allocated. * 
* Param - Varies with the message. Usually a pointer to info on * 
2 source and destination files, or names of translated files. * 
x Self - this is a handle to the translation routine itself. * 
* It is used to lock the routine in memory while it is in use.  * 
* QUTPUT : NONE * 
* RESULT : Varies with the message. Usually the status of a certain oper  * 
* ation. If AFE does not explicitly require a result the tran- * 
* slator must return a zero. * 
dA FA x de dedico fO doloe dede eee fede ede iie jefe dede defe dede Redde dee dede eee ote e eic dniee* ) 


function TranStr(Message : integer; VAR translateData : Handle; 
Param : longint; Self : handle) : longint; 
var 
trnpb : trnPtr; 
statRec,statrec2 : statHndl; 
oldres : integer; 
h : handle; 
err : OSErr; 
begin 
hlock (self); 
trnpb := POINTER (Param); 
statRec :- POINTER (translateData); 
case Message of 
trn Init : begin 
TranStr := DoInit (translateData, self,trnpb): 
end; 


trn Finis : begin 


TranStr := DoFinish(translateData); 
end; 
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(* £xtended CatInfo constants *} 


mdos = 'mdos'; 
pdos = 'pdos': 


(ProDOS access bits) 

pdReadable = $01; { File may be read } 

pdWritable = $02; { File may be written to } 

pdChanged = $20; { File has changed since last backup } 
pdRename = $40; { File may be renamed } 

pdDestroy = $80; { File may be destroyed } 


pdNormal = $C3; { A normal ProDOS file } 
pdLocked » $01; ( A Locked ProDOS file ) 


(ProDOS storage types) 

pdSeedling = 501; ( File is a seedling, only one data block } 
pdSapling = $02; ( File is a sapling, 2 to 256 data biocks } 
pdTree = $03; { File is a tree, 257 to 32768 data blocks } 
pdSubDir = $0D; { Pile is a subdirectory } 


(ProDOS version numbers) 
ProDosl] 0» 0;  ( ProDOS 1.0 } 


(MSDOS Attribute bits} 

msReadOniy = $01; { File is read-only } 

msHidden » $02; { File is hidden } 

msSystem = $04;  ( File is a system file } 

msVolume = $08; { Directory is the root } 

msSubDir = $10; { File is a subdirectory } 

msArchive = $20; { File has been written to and closed } 


{ REE AEAAAASE ASAE AACE AEE ARKEKARLETEAAKRKARRKKEAAANR 
* 

* constants for tprocs 

* 

sd pietre fte dine e fee ege diededendnnte feed feine ) 


tDstTooShort = -501; 


cfMacintosh = 0; 
cfASCIi =]; 
cfIBMPC 92; 


transInit = 0; 
transDone = 1; 
translotohi = 2; 
transhitolo = 3; 


trMultiDestFont = 1 
trMultiDestCountry = 2; 
trNonOnetoOne = 4; 
trOverStrike = 8; 


TYPE 
nameREC = RECORD 
namecnt : integer; 
names : array(O..maxdestnames) of str255; 
end; 
nameptr = “nameRec; 
namehdl = “nameptr; 
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trn Load : begin 


Do a GETRESOURCE for all of the resources that you might 
need during a translation. This does not guarantee that 

a *floppy shuffle" won't be needed, just helps the odds. 
Load the most likely to be used resources last so they will 
be the least likely to be purged. 


“el 
* ee ere * 


S 
oldres := curResFile; 
useResFile (stat rec** .myfRef) ; 
:= getResourcsa (‘ ICON’, statrec** .myID); 
= getResource (‘ICON', statrec**.myID+1) ; 
getRescurce ('ICON', statrec**.myID+2) ; 
getResource ('ICON',statrec^^.myID*3); 
getResource ('DITL',statrec^^ .myID!; 
getResource ('DLOG', stat rec^^ .myID); 
= getResource ('STR#', statrec** .myID); 
useResFile(oidres) ; 
{ don't bether bringing in the ABOUT text } 
TranStr := 0; 
end; 
trn About : begin 


aa on as es . 


rrr oo vo 


os oa 


If we want to tell the user about ourselves, we can put up 

our own dialog (in which case we return zero). If we want 

nothing done, we can return -l, whereupon Apple File Exch will 
inform the user that no information is available. 

If we want Apple File Exch to display the information, we can give 
it a (positive) resource ID of a TEXT resource containing 
information about us. 


i 
* ox X X x» Hh * * 
= 


TranStr := statrec**.myID; 


trn GetSettings : begin 


With this message, Apple File Exch is requesting a handle filled 
with data that can be stored in a document. Apple File 

Exchange allows the user to save and restore default settings 
("preferences", if you will) so that the user can launch 

the program and have each translation be in a state that 

they are familiar with. We have to do the NEWHANDLE call 

to create a handle of the correct size, Apple File Exch will 
dispose it later. If this call is not supported, return 

NIL or some (negative) error code. 


“si 
€ on * € Ko X *  * * 


— 


h :* translateData; 
( Create a new handle that points to a COPY of the global data ) 
err := HandToHand(h); { see Inside Mac vol II, p374 for details } 
if err = noerr 

then TranStr := ORD4(h) 

else TranStr := err; 
end; 
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tprf = RECORD 
lastEntry : integer: 
reserved : arrayí(1..231] of integer: 
tprocs : array(1..1000] of TPRCEntry; 
end; 

tprfPtr = ^tprf; 

tprfHndl = ^tprfPtr; 


header = RECORD 
branch : longint; 
sig  : resType: 
resnum : integer; 
versum : integer; 
vers : string(15]:; 
flags : integer; 
loCntry : integer; 
loCFam : integer; 
hiCntry : integer: 
hiCFam : integer; 
hdrrsrv : array([0..3] of longint; 
end; 
hdrPtr = “header; 
hdrüHndl = ^hdrPtr; 


TransText = RECORD 


crete : Ptr; 
trLen : Longint; 
trFont : integer; 
end; 


TransPB = RECORD 
verb : integer; 
featureflags: integer; 
result : OSErr; 
newcntry : integer; 
srcText : TransText; 
dstText : TransText; & 
tpRsrv : array[0..3] of longint; ; 
end; 


function CallFS(msg : integer; fsdata : ptr; pb :ptr; 
async : boolean; fsroutine : handle) : OSErr; 
INLINE $2057,$2050,$4E90; 


procedure CallLog(str : str255; cr : boolean; Indent : boolean; Logproc : procptr); 
INLINE $205F, $1F5F, $0001, $4E90; 


procedure CallErrLog(str : str255; cr : boolean; Indent : boolean; Logproc : procptr); 
INLINE $205F, $1FSP, $0001, $002F, $0080, $0001, $4E90; 


function CallStat(statmsg : str255; statpct : integer; destfnum : integer; 
statproc : procptr) : boolean; 
INLINE $205F, $4E90; 
function CallTProc(VAR params : TransPB; self : hdrHndl) : OSErr; 
INLINE $2057, $2050, $4E90; 


IMPLEMENTATION 


AFETrans.p 
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AFETrans.p 
Unit AFETrans; 
INTERFACE 


Uses 
(SLOAD MacLoad.L} MemTypes,QuickDraw,osIntf, toolIntf,packIntf,macPrint,script; 


CONST 
(* translator routine commands *) 
trn Init = 0; ( do any translator routine initialization } 
trn Finis * 1; { do any clean up and disposal } 


trn Get = 2; ( Return current status ) 

trn Set = 3; ( Set current status } 

= 4; ( User has requested item be checked in menu } 

= 5; ( User has requested item be unchecked in menu } 
trn NewName = 6; ( If recognized, return new name for selected file } 
trn File  - 7; ( If recognized, convert the selected file } 

trn Recognize = 8; ( Return NoErr if selected file is recognized } 
trn Appear = 9; { This routine is now listed in a menu } 

trn Disappear = 10; { This routine is no longer listed in a menu } 
trn Load = 11; { Pre-load any resources you might need } 

trn About = 12; ( Provide "About this translator" information } 
trn GetSettings=13; ( Get default information about the translator } 
trn SetSettings-14; ( Set default information about the translator } 


(* translator status bits *) 

trnActive = $0001; { item is checked } 
trnGray = $0002; ( item is grayed-out } 
trnBold = $0010; { item is bold } 
trnlItalic = $0020; ( item is italicized } 
trnUnderline= $0040; { item is underlined } 
trnOutline = $0080; { item is outlined } 
trnShadow = $0100; { item is shadowed } 
trnAbout = $0200: { About information is available for the item} 
trnUserl = $1000; { user bit 1 } 

trnUser2 = $2000; { user bit 2 } 

trmUser3 = $4000; { user bit 3 } 


{* miscellaneous constants *} 
maxdestnames = 15; 


accept = noerr; 
unAccept = 1; 
trnCancel = 2; 


{* File system op codes *) 

FFGetVinfo = l; FFSetVInfo = 2; FFFlushVol = $; 
FFOpen ~= 9; FFOpenRF = 10; FFLockRange = 11; 
FFUnLockRange = 12; FFRead 13; FFWrite = 14; 
FFGetFPos = 15; FFSetFPos = 16: FFGetEOF = 17; 
FFSetEOF = 18; FFAllocate = 19; FFAllocContig = 20; 
FFFlushFile = 21; FFClose = 22; FFCreate = 23; 
FFDirCreate = 24; FFDelete = 25; FFGetFInfo = 26; 
FFSetFInfo = 27; FFSetFLock = 28; FFRstFLock =» 29; 
FFSetFVers = 30; FFRename = 31; FFGetCatInfo = 32; 
FFSetCatInfo = 33; FFOpenWD = 35; FFCloseWD = 36; 
EFGetWDInfo = 37; FFOKFName = 41; FFMakeFName = 47; 
FFXGetCatinfo = 50; FFXSetCatInfo = 51; 


foreignFS = '4NFS'; 
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Example.r 


/* Example Translation inclusion Resource Definition File */ 
/* */ 


/* include any static resources like dialogs, strings, etc. */ 
include *"Exampie.rsrc"^; 


/* include the code itself */ 
include *:0bjects:Example.tmp" 'MCMc' (4000) as 'MCMC' (4000,“STR# Resources to Text..", PURGEABIE); 


/* include the About text */ 
read 'TEXT' (4000) "Exampie.txt"; 


/* Create a STRE resource containing all the error strings our translator */ 
/* produces. The str xxxxx are the constants used to reference each string ay 
/* in Example.p */ 

resource 'STR#* (4000) { { 


/* str error » 1; */ "An error occurred while "; 

/* str creating = 2; */ "creating the destination file: "; 

/* str opensrc = 3; */ "opening the source file: "; 

/* str opendst = 4; */ "opening the destination file: "; 

/* str getfinfo » 5; */ "getting information about the file: "; 

/* str setfinfo - 6; */ "setting the file type of the destination file: "; 

/* str reading = 7; */ "reading in the source file: "; 

/* str writing = 8; */ "writing out the destination file: "; 

/* str copying = 9; */ "Copying STR# rescurces.."; 

/* str initing = 10; */ "initializing the translator '"; 

/* str period = 11; */ "'."; 

/* str cant = 12; */ "It cannot translate from '*; 

/* str to = 13; */ "' to '"; 

/* str delsrc = 14; */ "deleting the original file (your translated data is in the file 
$$53AFE-TEMP$$3): *: 

/* str rendst = 15; */ “renaming the destination file (your translated data is in the file 
$$$AFE-TEMP$$$): "3 

/* str numstrings = 16; */ "Number of STR# resources in this file: "; 

/* str stringRes = 17; */ "String Resource Number * 

) h 


/* The following is used to create a different icon for the translator */ 
/* The new icon was created by using ResEdit to modify the standard «/ 
/* translator icon. For more detail see Inside Mac III, pp.10-13 */ 

/* define the resource type? as a string type */ 


/* The file "Signature.r" is created by the make file ("Example.make") and contains */ 
/* the signature resource (in this case, of type 'exmp') necessary for displaying */ 
/* à different icon */ 

/* The text in the "emp" resource will be diplayed when a Get Info is done on the */ 
/* translator in the Finder*/ 

#include ":objects:Signature.r^ 
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translateRec = RECORD 
trnLoqproc : procptr; { pointer to error log procedure } 
trnstatproc : procptr; ( pointer to status procedure ) 
trnfrID : integer; { resource ID of source FS } 
trntoID : integer: { resource ID of dest FS } 
trnfrData : ptr; { pointer to source FS global data } 
trntoData : ptr; { pointer to dest FS global data } 
trnResrv : integer; ( used by InterFile | 
trnfrVRef : integer; ( volume ref of source } 
trntoVRef : integer; ( volume ref of dest ) 
trnfrPar : longint; | parent ID of source } 
trntoPar : longint; ( parent ID of dest ) 
trnnames : namehdl; { handle to names of source/dest files} 
trnTested : boolean; ( TRUE if you've already looked at this 
file for recognition ) 
trnAccepted : boolean; (if TRNTESTED is true, this flag shows 
whether you recognized the file } 
trnCountry : integer; { country ID } 
END; 
trnPtr » ^translateRec; 


(* parameter blocks for extended CatInfo calls *) 


XFSType = (Mac,ProDOS,MSDOS); 
XCInfoPtr = ^XCInfoPBRec; 
XCInfoPBRec = RECORD 
( In the memo this was descrived as a pointer not a record } 
CInfo: CInfoPBRec; 
CASE xfs : XFSType OF 
Mac : 
(filler3 : longint); 
ProDOS : 
(auxtype : integer; ( ProDOS auxilary file type ) 
access : signedbyte;( read,write perm etc. ] 
storagetype : signedbyte:;( seedling, sapling, etc ) 


version : signedbyte:;( version ProDOS used ) 

minvers : signedbyte);( earliest ProDOS version useable } 
MSDOS : 

{attrib : signedbyte; ( read, write, hidden, etc ) 

filler4 : signedbyte); 


NL; 


pdosHndl = ^pdosPtr; 

pdosPtr = “pdosRec; 

pdosRec = RECORD 
auxtype : integer; 
access : signedbyte; 
storagetype : signedbyte; 
version : signedbyte; 
minvers : signedbyte; 
END; 


mdosHndl = ^mdosPtr; 
mdosPtr = ^mdosRec; 
mdosRec = RECORD 
attrib : signedbyte: 
filler3 : signedbyte; 
END; 


TPRCEntry = RECORD 
tprcID  : integer; 
curCharFam : integer; 
altCountry : integer; 
altCharFam : integer; 
end; 
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Example, file 7 


^A "We 4h "h "b "Uh "P "e P Gb à 


The example translator sources should live in a folder called 
*ExampleTrans" within the MPW folder. There should also be 

a folder within "ExampleTrans" called "Objects" which will contain 
the object files and other 'deletable' files. 


In the MAKE command line, the '-d' option is used to set the version 
number. In the next command line, the computer will sound two notes 
when it is done: if the notes go up, an error occurred; if the notes 
go down, all is well. 


directory (MPW)ExampleTrans 
make -f Example.make ‘Example Translator' -d vers='1.0B4' »doit 
doit ii {beep 1320; beep 880) 
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T- A MSS sÀ»sbC L. LLL AL DÉ]XDcx^-PX?TCREIEEIGISIIIRIIMIBIIMILLLL LIILMELVELECTLEZGCSCGFáÍ2IOZZECZEEBEZÉZIECLEELEELIEECICITTIIIIITTT]TTTT ITECIRÉIBPEÉL LLELEELLLTLLLLLILLIULISOAALDLÓ2ZLLZIAUOLOMAP 


Example.a 


“1 





se we Se 


File: Example.a 
Copyright 1986,1987 by Apple Computer, Inc. All Rights Reserved. 


ta Ya Be 





wa 


EXAMPLE TRANSLATION ROUTINE HEADER FOR APPLE FILE EXCHANGE 


The file provides the required header for a translator. 


Ne Ye "xa Fe da heo 


ba 


PRINT CGF 

INCLUDE  "'Traps.a' 
INCLUDE  "'ToolEqu.a' 
INCLUDE ‘QuickEqu.a’ 
INCLUDE  "'SysEqu.a' 
INCLUDE  'SysErr.a' 
PRINT ŒN 


MAIN 
IMPORT TranStr ; this is the procedure name of the Pascal code 


"a 





Re Ge 





HEADER 

STRING ASIS á 
jap TranStr ; branch to Pascal C 
dc.l 'tran' ? signature 

dc.w 4000 ; resource number (decimal) 
dc.w 1 ; my version number 


STRING PASCAL 

dc.w '1.0A1' : ASCII version of version 

dc.l $0000FFFF  ; Indicates we support all calls 
dc.l 0 ; Reserved 


ENDMAIN 
end 
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Example.make 


Obj = :objects: 
ADptions = 
POptions = 
LinkOptions = -i 


vers s temp 
Examp = (Obj)Example.a.o (Obj)Example.p.o 
{Obj} f : 


.à.0 f a 
echo “Assembling (DepOir)(Default|.a" 
{Asm} (AOptions) (DepDir)(Default).a -o {TargDir}(Default}.a.o 


Speo f p 
echo “Compiling (DepDir} (Default }.p” 
(Pascal) (POptions) (DepDir)(Default).p -o (TargDir} {Default}.p.o 


‘Example Translator’ f (Obj)Example.tmp Example.r Example.rsrc Example.make 
echo "Building Example Translator víversj" 
echo "/* Signature resource build file */" >{Obj}signature.r 
echo "type 'exmp' as 'STR ';" >>{Ob}}signature.r 
echo “resource 'exmp' (O,purgeable) d( " »»:objects:signature.r 
echo “d"Example Translator, vivers}, "date -d'd"" »»(Obj)signature.r 
echo "Q);* »»(0bj)signature.r 
rez types.r Example.r d 
-t VISA -c exp d 
-0 'Example Translator' 
setfile -a Bi 'Example Translator' 
(beep 880; beep 1320) 


T (0bj)Example.tmp f (Examp) 

echo "Linking Example Translator" 

Link (LinkOptions) (Examp) ð 
"(PLibraries)"Paslib.o d 
*"(Libraries)"Interface.o ð 
-rt MCMC=4000 -ra Main=0 -rn @ 

-t ‘TEMP’ -c '?272' ð 
-0 :0bjects:Example.tmp »(Obj)Examp.map 
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/* The BNDL id number (0) is necessary but not important, it is never used */ 
resource 'BNDL' (0) { 
‘exmp', 
0, 
{ 
/* Map the local icon number 0 to the actual icon resource 128 */ 
/* we use ICN instead of ICON so that the mask is included, the */ 
/* mask is how the icon looks highlighted */ 
'ICNE', 
{ 
0, 128 
» 
/* Map local FREF 0 to FREF 128 */ 
'FREF', 


0, 128 


/* Create a file reference resource of ide128 that associates type VISA */ 
/* with the icon of local ID = 0 ; */ 
resource 'FREF' (128) ( 
'"JISA', 
Q, 
LI 
y 
/* for this icon to be used with the translator tbe bundle bit */ 
/* must be set. This is done with the setfile -a B 'Example Tran' */ 
/* statement in MPW after building the translator with rez »/ 
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Differences Between the 
U.S. and International Versions 
of Apple File Exchange 


There are currently two versions of Apple File Exchange: 


m 
= 


the U.S. version (version 1.0.1) 
the international version (version Z1-1.0.1). 


Most of the differences between these two versions are in the ways they handle 
extended character sets: 


D 


When users select any of the text translators in the international version, a dialog 
box appears. In this dialog box, users can select whether Apple File Exchange 
interprets characters in the extended character set as control characters or as 
accented characters. 


When a user translating an MS-DOS file selects the “Remove unnecessary control 
characters” option, the U.S. version suppresses all characters with character codes 
greater than 128 hexadecimal. The international version translates characters in 
MS-DOS text files with character codes greater than 128 hexadecimal if they 
represent accented characters. 


When a user translating a ProDOS text file selects the “Make control characters 
visible” option, the U.S. version displays control characters with character codes 
greater than 128 hexadecimal. The international version does not display these 
characters; this permits the display of accented characters that are part of the 
Apple IIGS extended character set. 


The international version also provides a menu (the Country menu) that lets users - 
identify the version of system software for the Macintosh that they're using. This makes 
it possible to use one version of Apple File Exchange in all countries. 


D-1 


i EE 
doit 


echo “Compiling Example.p" 
Pascal Example.p -o :objects:Example.p.o 


echo "Linking Example Translator" 

Link -l :objects:Example.a.o :objects:Example.p.o ð 
*HD20:MPW:PLibraries:"Paslib.o 9 
"HD20:MPW:Libraries:"Interface.o 9 
-rt MCMC»4000 -ra Main=0 -rm 
-t 'TEMP' -c '2?22' Q 
-o :objects:Example.tmp »:objects:Examp.map 

echo "Building Example Translator vl.0B4" 

echo °/* Signature resource build file */" »:0bjects:signature.r 

echo "type 'exmp' as 'STR ';" »»:0bjects:signature.r 

echo "resource 'exmp' (Ü,purgeable) d( " >>:objects:signature.r 

echo "O"Example Translator, vl.0B4, “date -d'd*"" »»:objects:signature.r 

echo "0};" »»:objects:signature.r 

rez types.r Example.r à 
-t VISA -c exmp à 
-o 'Example Translator' 

setfile -a Bi 'Example Translator' 

(beep 880; beep 1320) 
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Appendix E 




















Apple File Exchange 
TProcs 


The tables in this appendix list the transliterations performed by Apple File Exchange 
TProcs. Most of these tables include two kinds of transliterations: 


C single-character transliterations that are performed when the "Change to closest 
single character" option for a translator is selected 


o multiple-character transliterations where certain characters are replaced by more 
than one character 


Only the tables for U.S. English TProcs list all transliterations. Other tables list only 
the characters that are different from the corresponding U.S. English table. 


For information about TProcs, see Chapter 2, “Writing Translators.” 











Macintosh to MS-DOS transliterations 


The following tables list the transliterations from the Macintosh character set to the 
corresponding MS-DOS character set. 


Macintosh to MS-DOS: U.S. English 


This TProc is used for U.S. English as well as for Australian English, British English, 
Canadian French, Dutch, Finnish, Flemish, French, German, Spanish, Swedish, Swiss 
French, and Swiss German. 


One to single character One to multipie characters 


Source Source Destination Destination Destination Destination 
character value character value character value 
A 128 A 142 A 142 
A 129 A 143 A 143 
C 130 C 128 C 128 
É 131 É 144 É 144 
N 132 N 165 N 165 
Ó 133 Ó 153 Ó 153 
Ü 134 Ü 154 Ü 154 

á 135 á 160 á 160 

à 136 à 133 à 133 


(continued) 


Source 
character 


" Diíi1'-407^6880 


 RgorE 
n 
3 
= 


|o POP VA OM KM Oo + 


mv ons ee nh pr Urb pe Hr pe dt - 


233 


237 


One to single character 
Destination 
value 


Destination 
character 


"5 46524417 OHH 


d——v^o099^*-7-*-*l*ooo»*z 
D 
| 
^a 


eoim) m^ (y (OA (P we (Ro oc 


234 
145 
237 
168 
173 
170 
251 
159 
247 
127 
174 
175 
46 

32 

133 
65 

79 

79 

111 
45 

196 


One to multiple characters 
Destination Destination 
character value 

Q 234 

z 145 


© 
N 


"A Ex a 
N 
VA 
am 


blank 32 


| d 
8891 
T 


45 
196 


39 


È 


246 


v 


152 
152 
47 

111 


62 


mmvad “SS A + 


t3 
bad 
ON 


me et m) 0^ (y Ct $^ Che »» © 
S 


141 
(continued) 
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+ 


à 





Macintosh to MS-DOS: Italian 


This transliteration is used only for Italian. It is the same as the U.S. English Macintosh 
to MS-DOS transliteration except for the characters listed. 


Source Source 
character value 
ü 150 

$ 164 

® 168 

© 169 

is 170 

, 226 

: 227 
960 228 


One to singie character 


Destination Destination 
character value 


ü 164 
o 64 
R 82 
C 67 
T 84 
39 
39 
o 111 


One to multiple characters 


Destination Destination 
character value 


ü 164 
@ 64 
(R) 

(C) 

TM 

: 39 
39 
960 





Macintosh to MS-DOS: Norwegian 


This transliteration is used only for Norwegian. It is the same as the U.S. English 
Macintosh to MS-DOS transliteration except for the characters listed. 


Source Source 


character value 
€ 162 
Ø 175 
¥ 180 
Ø 191 


One to single character 


Destination Destination 
character value 


C 99 

Ø 157 
y 121 
9 155 


One to multiple characters 


Destination Destination 
character value 


cent 

Ø 157 
yen 

Ø 155 


Macintosh to MS-DOS transiiteratlons 


E-5 


One to single character One to multiple characters 


Source $ource Destination Destination Destination Destination 
character value character vaiue character value 
4 137 à 131 a 131 
à 139 a 97 a~ 

a 140 a 134 a 134 
ç 141 ç 135 ç 135 
é 142 é 130 é 130 
è 143 è 138 è 138 
E 144 è 136 é 136 
é 145 é 137 é 137 
i 146 i 161 i 161 
i 147 i 141 i 141 
I 148 i 140 1 140 
i 149 i 139 i 139 
fi 150 N 165 N 165 
6 151 6 162 6 162 
Ó 152 Ò 149 ò 149 
ô 153 ô 147 ô 147 
Ö 154 Ö 148 Ó 148 
6 155 o 111 o~ 

ú 156 a 163 ú 163 
ü 157 ü 151 ù 151 
û 158 ü 150 ü 150 
ü 159 ü 129 ü 129 
+ 160 CT 194 E x 194 
i 161 bi 248 x 248 
€ 162 € 155 € 155 
& 163 & 156 £ 156 
$ 164 $ 36 $ 36 
e 165 e 249 e 249 
q 166 P 80 PI 

8 167 S 225 8 225 
® 168 r 114 Cr) 

© 169 c 99 (c) 

TM 170 t 116 tm 

: 171 ! 34 i 34 
E 172 46 ix 

+ 173 = 61 = / 

Æ 174 Æ 146 Æ 146 
Ø 175 Ø 237 Ø 237 
oo 176 oo 236 on 236 
+ 177 + 241 t 241 
sS 178 sS 243 sS 243 
2 179 2 242 2 242 
¥ 180 ¥ 157 ¥ 157 
u 181 u 230 p 230 
g 182 " 235 ð 235 
Zz 183 2 228 2: 228 
I1 184 x 227 x 227 
x 185 x 227 p^ 227 
J 186 J 244 j 224, 245 
à 187 à 166 s 166 
9 188 o 167 2 167 
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Source 
character 


é 
comer 
1/2 
1/4 


oR 4$ TAN H BOMBS EUWH STEHAFQaMA IAB’ *~ 


N p<’ 


253 


One to single character 
Destination 
value 


Destination 
character 


9o i +“"TANH FE OCMWASvH*atFoMmMa j Um» *- pws t 


NÐ £’ 


192 


176 
175 


85 
61 
177 
179 
178 
186 


214 
197 
161 
165 


195 
110 


One to multiple characters 


Destination 
value 


Destination 
character 


é 

l> 
1/2 
1/4 


—-mpwe eer 


4 


AMA 


sigma> 


^ -t'E 


phi» 


Ags vDH ” 


oreo UANH Ic 


An 
A2 


MS-DOS to Macintosh fransiiterations 


epsilon> — 


192 


194 


188 
189 
182 
176 
175 


85 

61 

177 
179 
178 
186 
186 
214 


161 
165 


195 


E-7 


Source 
character 


OO 


"7" CC? CO s 


245 
246 
247 
248 
249 
250 
251 
252 
253 
254 
255 


One to 


Destination 
character 


iro" fro ooh Oo © 


ie character 


Destination 
value 


162 
147 
219 
149 
163 
150 
151 
105 
94 
126 
45 
44 
250 
248 
44 
34 
44 
255 


Macintosh to MS-DOS: Danish 


This transliteration is used only for Danish. It is the same as the U.S. English 
Macintosh to MS-DOS transliteration except for the characters listed. 


One fo multiple characters 


Source 
character 


ü 


PORDCOO rmm mare bp FG HS eKAH © 


E-4 


Source 
value 
190 — 
162 
173 
175 
180 
191 
198 
203 
217 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
241 
242 
243 
244 


One fo 


character 
ü 


CO COOOTT ITM PMP RK HOSE KOO 


e character 
Destination Destination 


value 


164 
99 
35 
157 
157 
155 
127 
65 


G9 dgdgdoogo3c 


Destinatlon 
character 
6 

ô 
<Apple> 


|» 


Destination 


character 


ü 
«cent» 


O' 
OA 
o 
U' 
U^ 
U 
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One to multiple characters 


Destination 
value 


162 
147 


149 
163 
150 
151 
105 
94 
126 
45 
44 
250 
248 
44 
34 
44 
255 


Destination 
value 


164 


35 
157 
89 
155 
127 





MS-DOS to Macintosh: Italian 


This transliteration is used only for Italian. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 


One to single character One to multiple characters 


Source Source Destination Destination Destination Destination 
character value character value character value 
re 229 O 111 <SIGMA> 





MS-DOS to Macintosh: Norwegian 


This transliteration is used only for Norwegian. It is the same as the U.S. English 
MS-DOS to Macintosh transliteration except for the characters listed. 


One fo single character One to muitipie characters 
Source Source Destination Destination Destination Destination 
character value character value character value 
e 155 o 191 Ø 191 
Ø 157 Ø 175 Ø 175 
o 232 a 219 «pi» 
€ 238 E 69 <ypsilon> 





MS-DOS to Macintosh: Spanish 


This transliteration is used only for Spanish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 


One t0 singie character One to muitiple characters 
Source Source Destination Destination Destination Destination 
character value character value character value 
€ 238 E 9 <épsilon> 


MS-DOS to Macintosh: Swedish 


This transliteration is used only for Swedish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 


One to single character One to multiple characters 
Source Source Destination Destination Destination Destination 
character value character value character value 
o 232 g 219 <fi> 
MS-DOS to Macintosh 1iransliterations E-9 


ee EEE 
MS-DOS to Macintosh transliterations 


The following tables list the transliterations from one of the MS-DOS character sets to 
the Macintosh character set. 


MS-DOS to Macintosh: U.S. English 


This transliteration is used for U.S. English as well as for Australian English, British 
English, Canadian French, Dutch, Flemish, French, Swedish, and Swiss French. 


One to single character One to muitiple characters 


Source Source Destination Destination Destination Destination 
character value character value character value 
Ç 128 Ç 130 ¢ 130 
Ü 129 ü 159 a 159 
é 130 é 142 é 142 
à 131 å 137 å 137 
ä 132 ä 138 a 138 
a 133 a 136 a 136 
4 134 a 140 a 140 
ç 135 ç 141 ¢ 141 
é 136 é 144 é 144 
é 137 € 145 é 145 
e 138 e 143 è 143 
1 139 1 149 í 149 
i 140 i 148 1 148 
i 141 1 147 i 147 
A 142 A 128 A 128 
A 143 A 129 A 129 
É 144 É 131 É 131 
z 145 z 190 z 190 
Æ 146 Æ 174 Æ 191 
ô 147 ô 153 Ó 153 
Ó 148 Ó 154 Ó 154 
Ò 149 Ó 152 ò 152 
û 150 û 158 û 158 
ù 151 ù 157 ù 156 
y 152 y 216 y 216 
Ó 153 Ó 133 Ó 133 
Ü 154 Ü 134 U 134 
¢ 155 ¢ 162 ¢ 162 
& 156 & 163 & 163 
¥ 157 Y 180 ¥ 180 
Pts 158 P 80 Pt 

f 159 f 196 f 196 
4 160 4 135 á 135 
í 161 í 146 i 146 
6 162 6 151 6 151 
ü 163 ü 156 ú 156 
ñ 164 ü 150 ñ 150 
Ñ 165 Ñ 132 Ñ 132 
: 166 à 187 3 187 
2 167 9 188 2 188 
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Source 
character 


D WE OF 7 TOF c 1. b dde i * * D à 9407 OR H ® 7-—acjMrEXivi^ng Gat c * 20 


207 


219 


One to singie character 
Destination Destination 
character value 


c 9 
t 116 
39 
46 
61 
65 
79 
37 
43 
60 
62 
89 
117 
100 
83 
80 
112 
83 
97 
111 
79 
97 
111 
63 
33 
45 
118 
102 
61 
100 
60 
62 
46 
32 
65 


CG Swe oo. Se ON dm es 8 OOF rE VAQRE™MS ' ON OOK ND VANAR KVA FLOP EE’ 


One to multipie characters 


Destination Destination 

character value 

(c) 

um 

' 39 

-/ 

AE 

O/ 

<infinity> 

+. 

<= 

>= 

Y= 

u 117 

d 100 

«SIGMA» 

PI 

pi 

«integral» 

4. 

o. 

«omega» 

ae 

o/ 

? 63 

33 

- 45 

<radical> 

f 102 

<DELTA> 

<< 

>> 

blank 32 

A’ 

A- 

Q- 

OE 

oe 

- 45 

- 45 

39 

39 

: 39 

i 39 

<divided by> 

<> 

ye 

YE 

/ 47 

o 111 
(continued) 
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MS-DOS to Macintosh: Danish 


This transliteration is used only for Danish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the characters listed. 


Source Source 
character value 


155 
157 
224 
226 
229 
231 
232 
233 
237 
238 
239 
240 


ev mea coOQ-udia"nim.] uM 


One to single character 
Destination Destination 
character value 

Ø 191 

Ø 175 

a 97 

G 71 

S 115 

t 116 

F 70 

T 84 

o 191 

e 101 

^ 94 

= 61 


MS-DOS to Macintosh: Finnish 


This transliteration is used only for Finnish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 


Source Source 
character value 
® 232 


One to single character 


Destination 
character 


Destination 
value 


219 


MS-DOS to Macintosh: German 


This transliteration is used only for German and Swiss German. It is the same as the 
U.S. English MS-DOS to Macintosh transliteration except for the characters listed. 


Source . Source 
character value 
r 226 

o 229 

Y 231 

o 232 

0 233 

€ 238 

A 239 


One to single character 


Destinatlon 
character 


ctm 9"u-o j 


Destination 
value 


194 
111 
160 
219 
188 
69 

85 


One to multiple characters 


Destination Destination 
character value 


o 191 
Ø 175 
<alfa> 
<GAMMA> 
<sigma> 

<tau> 116 
<PHI> 
<THETA> 

o 191 
«epsilon» 
<falles> 


One to multiple characters 


Destination Destination 
character value 


«pii? 


One to multiple characters 


Destination Destination 
character vatue 


«gamma» 
«Sigma» 
«tau» 

«Phi» 
«theta» 
«Epsilon» 
«intersection» 
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Macintosh fo ProDOS: Danish 


This transliteration is used only for Danish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source 
value 
129 
140 
161 
162 
163 
165 
166 
167 
173 
174 
175 
176 
181 
182 
184 
185 
186 
189 
190 
191 
194 
195 
197 
196 
203 
214 
215 
224 
225 
228 


Source 
character 


+ Ot DI LI AR D^*-zvr-a8GpAm*w€4*.In^ 99» 


g 


Macintosh to ProDOS: Dutch and Flemish 


One to single character 
Destination Destination 
character value 

93 (129 on GS) 
125 (140 on GS) 
111 

99 

76 

42 

80 

115 

35 

91 (174 on GS) 
92 (175 on GS) 
45 

109 

100 

80 

112 

83 

79 

123 (190 on GS) 
124 (191 on GS) 
45 

86 

126 

68 

65 

47 

60 

116 

42 

37 


FT AP OI < ' ORN OND VAR ' ARII Ina 


One to multiplie characters 
Destination Destination 
character value 

A 93 (129 on GS) 
4 125 (140 on GS) 
<grader> 
<cent> 
<pund> 
+ 42 

Pg 

ss 

# 35 

Æ 91 (174 on GS) 
Ø 92 (175 on GS) 
<uendelig> 

«my» 

«delta» 

«PI» 

« pi? 

<integralet> 

<OMEGA> 

z 123 (190 on GS) 
Ø 124 (191 on GS) 
21 

«rod» 

«DELTA» 

A^ 

«divideret med» 
«» 

t 116 
? 42 
960 


This transliteration is used only for Dutch and Flemish. It is the same as the U.S. 
English Macintosh to ProDOS transliteration except for the characters listed. 


Source 
value 
7 172 

x 161 
¢ 162 
& 163 
oo 176 
J 186 
Y 195 
* 214 


One to e character 
Destination Destination 
character value 

7 126 (172 on GS) 
© 111 

c 99 

L 76 

96 37 

S 83 

V 118 

/ 47 


One to multiple characters 


Destination Destination 
character value 


<graden> 
<cent> 

<pond> 
<oneindig> 
<integraalteken> 
<wortelteken> 
<gedeeld door> 


Macintosh to ProDOS 1transliterations E-13 


ET E RRLEBLLÁEELCULULOLo 
Macintosh to ProDOS transliterations 


The following tables list the transliterations from the Macintosh character set to the 
corresponding ProDOS character set. 


Macintosh to ProDOS: U.S. English 
This transliteration is used for U.S. English as well as for Australian English. 


One to single character One to multiple characters 
Source Source Destination Destination Destination Destination 
character value character value character value 
A 128 A 65 A" 
A 129 A 65 AA 
C 130 C 67 C, 
É 131 E 69 E* 
N 132 N 78 N~ 
Ó 133 O 79 oO" 
Ü 134 U 85 U* 
á 135 a 97 a' 
a 136 a 97 a^ 
4 137 a 97 aA 
4 138 a 97 a” 
i 139 a 97 a~ 
å 140 2 97 aa 
€ 141 c 99 C, 
é 142 e 101 e 
è 143 e 101 e` 
é 144 e 101 e^ 
ë 145 e 101 e" 
í 146 i 105 i’ 
i 147 i 105 i` 
î 148 i 105 iA 
ïi 149 i 105 i" 
ñ 150 n 110 n- 
6 151 o 111 o' 
d 152 o 111 o^ 
ô 153 o 111 o^ 
Ó 154 o 111 o" 
6 155 o 111 o~ 
ú 156 u 117 u' 
ù 157 u 117 u` 
û 158 u 117 uA 
ü 159 u 117 u" 
t 160 t 116 t 116 
s 161 O 111 <degrees> 
¢ 162 c 99 <cents> 
£ 163 L 76 <pound> 
§ 164 $ 36 $ 
E 165 o 111 á 42 
q 166 P 80 P! 
$ 167 B 66 B 66 
® 168 fr 114 (r) 
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Macintosh to ProDOS: German 


This transliteration is used only for German and Swiss German. It is the same as the 
U.S. English Macintosh to ProDOS transliteration except for the characters listed. 


One to single character 


Source Source 
character value 


128 
132 
133 
134 
138 
139 
150 
154 
155 
159 
161 
162 
163 
164 
167 
176 
183 
186 
189 
195 
197 
198 
204 
205 
214 
224 
247 


ut t Coe E LNMI 0 * In ^ 9 € Or O Be M CS O ZZ pm: 


Destination 


character 


SN OFPAIMOMNPRNMNOEKOSHAXABMO OZ A 


Destination 
value 


91 (128 on GS) 
78 

92 (133 on GS) 
64 (134 on GS) 
123 (138 on GS) 
97 

110 

124 (154 on GS) 
111 

125 (159 on GS) 
111 

99 

76 

93 (164 on GS) 
126 (167 on GS) 
37 

83 

83 

79 

86 

61 

100 

65 

79 

47 

124 

45 


One to mulfiple characters 
Destination Destination 
character value 


A" 
N- 
Oo" 
U" 
2" 


«Grad» 
«Cents» 
«Pfund» 
$ 36 
B 66 
<Unendlich> 
<Sigma> 
«Integral» 
«Omega» 
«Wurzel» 
«Delta» 

A- 

O- 

<geteilt durch> 


- 45 


Macintosh to ProDOS transilterations 


E-15 


One to single character One to multiple characters 


$ource Source Destination Destination Destination Destination 

character value character value character value 

< 220 < 60 < 60 

> 221 > 62 > 62 

fi 222 f 102 fi 

f 223 f 102 fl 

+ 224 | 124 {= 
225 42 : 

226 44 44 

LI 227 , 44 ;! 

Sho 228 % 37 % 37 

A 229 A 65 AA 

Ê 230 E 65 || E^ 

Á 231 A 65 A' 

E 232 E 69 E" 

È 233 E 69 E` 

Í 234 I 73 I 

I 235 I 73 IA 

ï 236 I 73 I" 

I 237 I 73 r 

6 238 O 79 O' 

Ó 239 O 79 O^ 

é 240 2 97 <Apple> 

Ò 241 Q 79 oO” 

Ü 242 U 85 U' 

Ü 243 U 85 UA 

U 244 U 85 U 

i 245 i 105 i 105 

i 246 A 94 A 94 

r 247 ~ 126 ~ 126 

7 248 - 45 - 45 

~ 249 : 44 44 
250 z 42 : 42 
251 i 42 7 42 

; 252 : 44 i 44 


Macintosh to ProDOS: British English 


This transliteration is used only for British English. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the character listed. 


One to single character One to multiple characters 
Source Source Destination Destination Destination Destination 
character vatue character value character value 
& 163 & 35 (163 on GS) <pound> 
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Macintosh to ProDOS: Norwegian 


This transliteration is used only for Norwegian. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source 
character 


+ La "3 Qh e O A> e 


One to single character 


Source Destination Destination 
value character value 

129 A 93 (129 on GS) 
140 à 125 (140 on GS) 
161 o 111 

162 č 99 

163 L 76 

174 Æ 91 (174 on GS) 
175 Ø 92 (175 on GS) 
176 % 37 

186 S 83 

190 z 123 (190 on GS) 
191 o 124 (191 on GS) 
195 v 118 

214 / 47 


Macintosh to ProDOS: Spanish 


This transliteration is used only for Spanish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source 
character 


gO ne oom Z 


^ f*. 


One to singie character 


Source Destination Destination 
value character value 

132 N 92 (132 on GS) 
141 ¢ 125 (141 on GS) 
150 fi 124 (150 on GS) 
161 x 123 (161 on GS) 
162 C 99 

163 & 35 (163 on GS) 
164 $ 64 (164 on GS) 
176 96 37 

192 é 93 (192 on GS) 
193 i 91 (193 on GS) 
214 / 47 


One to multiple characters 


Destination Destination 
character value 


AA 

aa 

<grader> 
<cent> 
<pund> 

AE 

O/ 
<uendelig> 
<integraltegn> 
ae 

o/ 
<kvadratrot> 
<delt p> 


One to multiple characters 


Destination Destination 
character value 
N- 

C, 

n~ 

<grados> 
<centimos> 
<libra> 

$ 36 
<infinito> 

? 63 

! 33 


<dividido por> 
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Macintosh to ProDOS: Finnish 


This transliteration is used only for Finnish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source Source 
character value 


128 
129 
133 
138 
140 
154 
161 
162 
163 
176 
186 
195 
214 


4$ 47^. in ^ OO MD & Cx D> e: 


One to single character 


Destination Destination 
character value 


111 
99 
76 
37 
83 
118 
47 


V « OM BON 0 O0 » » Cx p» 


Macintosh to ProDOS: French 


This transliteration is used only for French, Canadian French, and Swiss French. It is 
the same as the U.S. English Macintosh to ProDOS transliteration except for the 


characters listed. 


Source Source 
character value 


136 
141 
142 
143 
157 
161 
163 
164 
172 
176 
183 
186 
189 
195 
198 
214 


i-i o C OO 


to —DT-^ud 
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One to single character 
Destination Destination 
character value 


1th OM Qr mM & 


37 
83 
83 
79 
118 
100 
47 


xas Onne 


91 (128 on GS) 
93 (129 on GS) 
92 (133 on GS) 
123 (138 on GS) 
125 (140 on GS) 
124 (154 on GS) 


64 (136 on GS) 
92 (141 on GS) 
123 (142 on GS) 
125 (143 on GS) 
124 (157 on GS) 
91 (161 on GS) 
35 (163 on GS) 
93 (164 on GS) 
126 (172 on GS) 


One to muitiple characters 


Destination Destination 
character value 


A" 
AA 
O" 
a" 
aa 
o" 
«aste» 


— «sentti» 


«punta» 
<aareton> 
<integraali> 
<juuri> 
<jakomerkki> 


One to multiple characters 
Destination Destination 
character value 


~ 


<degrés> 
<livre> 


$ 36 


<infini> 
<sigma> 
<intégrale> 
<oméga> 
<racine> 
«delta» 
«divisé par» 


ProDOS to Macintosh transliterations 


For all members of the Apple II family of computers other than the Apple IIGS, there 
are 12 characters in the character set that vary from country to country. The ASCII 
codes for these 12 characters are the same in ail countries, but there are differences in 
the actual characters. The tables in this section list these 12 characters for each 
country. All others characters are unchanged by transliteration; for example, c in a 
ProDOS source file remains c after it has been transliterated. 


One-character-to-multiple-character transliterations are not available for ProDOS to 
Macintosh translators. 


ProDOS to Macintosh: U.S. English 
This TProc is used for U.S. English as well as for Australian English. 


One to closest character 


Source Source Destination Destination 
character value character value 
* 35 * 35 

$ 36 $ 36 

Q 64 Q 64 

[ 91 [ 91 

A 92 \ 92 

] 93 } 93 

A 94 A 94 

à 96 ` 96 

{ 123 { 123 

| 124 | 124 

) 125 } 125 
~ 126 ~ 126 


ProDOS to Macintosh: British English 
This transliteration is used only for British English. 
One to closest character 


Source Source Destination Destination 
character value character value 
& 35 (163 on GS) & 163 
$ 36 $ 36 

@ 64 e 64 

[ 91 [ 91 

\ 92 \ 92 

] 93 ] 93 

^ 94 ^ 94 

` 96 i 96 

{ 123 { 123 

| 124 l 124 

} 125 } 125 
- 126 ~ 126 


ProDOS to Macintosh transliterations E-19 


Macintosh to ProDOS: Italian 
This transliteration is used only for Italian. It is the same as the U.S. English Macintosh 


to ProDOS transliteration except for the characters listed. 


Source Source 
character value 


129 
132 
136 
139 
140 
141 
142 
143 
147 
150 
152 
155 
157 
160 
161 
162 
163 
164 
166 
168 
169 
170 
173 
176 
181 
182 
184 
185 
186 
195 
197 
204 
205 
209 
216 
217 
224 
226 


COT mg C o x C ODE STA YE g ROGA In ^ iore o Oo DU v OO ie m mue 


251 


One to single character 


Destination 
character 


e *- COP HMR TEMS OR 14 090v0c€ £I dOsmveio*«coonmeonrrtZ» 


Destination 
value 


65 


78 

123 (136 on GS) 
97 

97 

92 (141 on GS) 
93 (142 on GS) 
125 (143 on GS) 
126 (147 on GS 
110 

124 (152 on GS) 
111 

96 (157 on GS) 
43 

91 (161 on GS) 
99 

35 (163 on GS) 
64 (164 on GS) 
80 

82 

67 

Bá 

61 

37 

117 

100 


E-16 Appendix E: Apple File Echange TProcs 


One to multipie characters 


Destination Destination 
character value 


A? 

N- * 

à 123 (136 on GS) 
a- 

2° 

ç 92 (141 on GS) 
é 93 (142 on GS) 
e 125 (143 on GS) 
1 126 (147 on GS) 
n- 

ò 124 (152 on GS) 
0- 

ù 96 (157 on GS) 
+ 43 

e 91 (161 on GS) 
«centesimi» 

& 35 (163 on GS) 
$ 64 (164 on GS) 
PP 

(R) 

(C) 

TM 

«» 

«infinito» 

m 109 
«DELTA» 

«P-greco» 

«p-greco» 

«integrale» 

«radice» 

A- 

O- 

y" 

y" 

++ 

t 39 

' 39 

960 

E' 

r | 

«Apple» 

Q' 

U' 

' 39 

: 46 

s 91 (161 on GS) 


ProDOS to Macintosh: Finnish 


This transliteration is used only for Finnish. 


Source 
character 


7 > OF om & 


I > O Ax 


Source 
value 


35 

36 

64 

91 (128 on GS) 
92 (133 on GS) 
93 (129 on GS) 
94 | 

96 

123 (138 on GS) 
124 (154 on GS) 
125 (140 on GS) 
126 


One to closest character 


Destination Destination 
character value 


35 
36 
64 
128 
133 
129 
94 
96 
138 
154 
140 
126 


re OM 8 Se Or ge & 


ProDOS to Macintosh: French 
This transliteration is used for French, Canadian French, and Swiss French. 


Source 
character 


om V* [n 


50 £0 t » wm 


Source 
value 


35 (163 on GS) 
36 

64 (136 on GS) 
91 (161 on GS) 
92 (141 on GS) 
93 (164 on GS) 
94 

96 

123 (142 on GS) 
124 (157 on GS) 
125 (143 on GS) 
126 (172 on GS) 


One to closest character 


Destination Destination 
character value 


163 
36 

136 
161 
141 
164 
94 

96 

142 
157 
143 
172 


om ^ $n 


PO pO 4 » wo 


ProDOS to Macintosh transliterations 


E-2] 


Macintosh to ProDOS: Swedish 


This transliteration is used only for Swedish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source 
value 


128 
129 
133 
138 
140 
154 
161 
162 
163 
176 
183 
195 
198 
214 


Source 
character 


+ > =~! 8 ine 9 Qu We RO} De pei 


E-18 


One to 


Destination 
character 


o Qi PR & Cx ue pe 


"-ügusdugtuno 


le character 


Destination 
value 


91 (128 on GS) 
93 (129 on GS) 
92 (133 on GS) 
123 (138 on GS) 
125 (140 on GS) 
124 (154 on GS) 
111 

99 

76 

37 

83 

118 

100 

47 
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One to muitiple characters 


Destination Destination 
character value 


A" 
AA 
Q " 
a a 
aa 
o A 
<grader> 
<cent> 
<pund> 
«oándlighet» 
«sigma» 
«rot» 
<delta> 
<dividerat med> 


ProDOS to Macintosh: Spanish 


This transliteration is used only for Spanish. 


Source 
character 


UO w 0 ^ » 0 A” S A in 


Source 
value 


35 (163 on GS) 
36 


64 (164 on GS) 
91 (193 on GS) 
92 (132 on GS) 
93 (192 on GS) 
94 

96 

123 (161 on GS) 
124 (150 on GS) 
125 (141 on GS) 
126 


One !o closest character 
Destination Destination 
character value 


163 
36 

164 
193 
132 
192 
94 

96 

161 
1S0 
141 
126 


UO nm 9o ^ »^ gw ln 


ProDOS to Macintosh: Swedish 
This transliteration is used only for Swedish. 


d 
a 
e 


re Om >> OP eo s 


Source 
value 


35 

36 

64 

91 (128 on GS) 
92 (133 on GS) 
93 (129 on GS) 
94 

96 

123 (138 on GS) 
124 (154 on GS) 
125 (140 on GS) 
126 


One to closest character 


Destination Destination 
character value 


35 
36 
64 
128 
133 
129 
94 
96 
138 
154 
140 
126 


Le oe >> ORG & 


ProDOS to Macintosh transiiteratlons 


E-23 


ProDOS to Macintosh: Danish and Norwegian 


This transliteration is used only for Danish and Norwegian. 





One to closest character 
Source Source Destination Destination 
character value character value 
* 35 # 35 
$ 36 $ 36 
9 64 Q 64 
Æ 91 (174 on GS) Æ 174 
Ø 92 (175 on GS) Ø 175 
Å 93 (129 on GS) A 129 
A 94 A 94 
à 96 ` 96 
z 123 (1900n GS 2æ 190 
o 124 (191 on GS) o 191 
a 125 (140 on GS) a 140 
~ 126 ~ 126 


ProDOS to Macintosh: Dutch and Flemish 
This transliteration is used only for Dutch and Flemish. 


One to closest character 
Source Source Destination — Destination 
character value character value 
s 35 # 35 
$ 36 $ 36 
Q 64 Q 64 
[ 91 [ 91 
A 92 \ 92 
] 93 ] 93 
^ 94 ^ 94 
à 96 : 96 
{ 123 { 123 
| 124 | 124 
) 125 ) 125 
7 126 (172 on GS) ^ 172 
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ProDOS to MS-DOS: Danish and Norwegian 


This transliteration is used only for Danish and Norwegian. 


Source 
character 


‘>> ORO & 


io 


ProDOS to MS-DOS: Dutch and Flemish 
This transliteration is used only for Dutch and Flemish. 


Source 
character 


;o—— ^79 & 


Source 
value 


35 

36 

64 

91 (174 on GS) 
92 (175 on GS) 
93 (129 on GS) 
94 

96 

123 (190 on GS) 
124 (191 on GS) 
125(140 on GS) 
126 


No Us 
REVLSVRSAS f 


126 (172 on GS) 


One to closest character 
Destination 


Destination 
character 


‘>> Ohoes 


i a BH 


value 


35 
36 
64 
146 
157 
143 
94 
96 
145 
155 
134 
126 


One to closest character 
Destination Destination 
character value 

* 35 

$ 36 

e 64 

[ 91 

\ 92 

] 93 

^ 94 

` 96 

{ 123 

| 124 

} 125 

- 126 


ProDOS to MS-DOS transliterations 


E-25 


ProDOS to Macintosh: German 


This transliteration is used only for German and Swiss Gerrnan. 


One to closest character 


Source Source Destination — Destination 
character value character value 
* 35 * 35 

$ 36 $ 36 

$ 64 (164 on GS) $ 164 
A 91 (128 on GS) A 128 
Ó 92 (133 on GS) Ó 133 
Ü 93 (1340n GS) ÙÜ 134 
A 94 A 94 

: 96 è 96 

à 123 (138 on GS a 138 
6 124 (154 on GS) 6 154 
ü 125 (159 on GS) ü 159 
8 126 (167 on GS 8 167 


ProDOS to Macintosh: Italian 
This transliteration is used only for Italian. 


One to closest character_ 
Source Source Destination Destination 
character value character value 
£ 35 (163 on GS) & 163 
$ 36 $ 36 
$ 64 (164 on GS) $ 164 
" 91 (161 on GS) o 161 
¢ 92 (141 on GS) ¢ 141 
é 93 (142 on GS) é 142 
^ 94 ^ 94 
ù 96(1570n GS) ù 157 
a 123 (136 on GS) à 136 
ò 124 (152 on GS) ò 152 
à 125 (143 on G) è 143 
i 126 (147 on GS) 1 147 
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ProDOS to MS-DOS: German 


This transliteration is used only for German and Swiss German. 


Source 
character 


1 > oO pit ^ & 


mec: OF M 


Source 
value 


35 


36 

64 (164 on GS) 
91 (128 on GS) 
92 (133 on GS) 
93 (134 on GS) 
94 

96 

123 (138 on GS) 
124 (154 on GS) 
125 (159 on GS) 
126 (167 on GS) 


One to closest character 
Destination 


Destination 
character 


Ac om 7 > Ch» 9 


ProDOS to MS-DOS: Italian 
This transliteration is used only for Italian. 
One to closest character . 


Source 
character 


o ^ 4^ bn 


C (yv Qr 9» £C > hm 


Source 
value 


35 (163 on GS) 
36 


64 (164 on GS) 
91 (161 on GS) 
92 (141 on GS) 
93 (142 on GS) 
94 


96 (157 on GS) 

123 (136 on GS) 
124 (152 on GS) 
125 (143 on GS) 
126 (147 on GS) 


Destination 
character 


C (WO Oe > mM © WH [n 


value 


35 
36 
36 
142 
153 
154 
94 
96 
132 
148 
129 
225 


156 
36 

64 

248 
135 
130 
94 

151 
133 
149 
138 
141 


Destination 
lue 


ProDOS to MS-DOS transliterations 


E-27 


SSS SSS 


ProDOS to MS-DOS transliterations 


For all members of the Apple II family of computers other than the Apple IGS, there 
are 12 characters in the character set that vary from country to country. The ASCII 
codes for these 12 characters are the same in all countries, but there are differences in 
the actual characters. The tables in this section list these 12 characters for each 
country. All others characters are unchanged by transliteration; for example, c in a 
ProDOS source file remains c after it has been transliterated. 


One-character-to-multiple-character transliterations are not available for ProDOS to 
MS-DOS translators. 





ProDOS to MS-DOS: U.S. English 
This TProc is used for U.S. English as well as for Australian English. 
. One to closest character 


Source Source Destination Destination 
character value character value 
# 35 * 35 

$ 36 $ 36 

Q 64 @ 64 

[ 91 [ 91 

A 92 \ 92 

] 93 ] 93 

^ 94 ^ 94 

: 96 i 96 

( 123 { 123 

i 124 | 124 

) 125 ) 125 
~ 126 ~ 126 


ProDOS to MS-DOS: British English 
This transliteration is used only for British English. 
One to closest character 


Source Source Destination Destination 
character value character value 
& 35 (163 on GS) £ 156 

$ 36 $ 36 

9 64 @ 64 

[ 91 [ 91 

\ 92 \ 92 

] 93 ] 93 

^ 94 ^ 94 

` 96 : 96 

{ 123 { 123 

i 124 { 124 

} 125 } 125 

= 126 ~ 126 
E-24 Appendix E: Apple File Exchange TProcs 


- eee xA gee S 0 TT 


MS-DOS to ProDOS transliterations 


The following tables list the transliterations from an MS-DOS character set to the 
corresponding ProDOS character set. 


MS-DOS to ProDOS: U.S. English 
This TProc is used for U.S. English as weil as for Australian English. 


One to closest character One to multiple characters 
Source Source Destination Destination Destination Destination 
character value character value character value 
C 128 C 67 C, 
ü 129 u 117 u" 
é 130 e 101 e' 
a 131 a 97 aA 
i 132 a 97 a" 
a 133 a 97 a! 
à 134 a 97 2a 
¢ 135 c 99 C, 
é 136 e 101 e^ 
é 137 e 101 e" 
è 138 e 101 e 
1 139 i 105 i" 
i 140 i 105 iA 
i 141 i 105 i‘ 
A 142 A 65 A" 
A 143 A 65 AA 
É 144 E 69 E' 
z 145 a 97 ae 
Æ 146 A 65 AE 
ô 147 O 111 OA 
Ó 148 re) 111 o" 
Ò 149 O 111 o' 
0 150 u 117 u^ 
ü 151 u 117 u’ 
y 152 y 121 y" 
Ó 153 O 79 e 
Ü 154 U 85 U" 
t 155 C 99 «cents» 
& 156 L 76 «pound» 
¥ 157 Y 89 Y= 
Pts 158 P 80 Pt 
f 159 f 102 f- 
4 160 a 97 a' 
i 161 i 105 i' 
6 162 Oo 111 o! 
ü 163 u 117 u' 
ü 164 n 110 n~ 
Ñ 165 N 78 N~ 
$ 166 2 97 a. 
i 167 a} 111 o. 
i 168 ? 63 ? 63 


MS-DOS to ProDOS fransiiterations 


E-29 


ProDOS to MS-DOS: Finnish 
This transliteration is used only for Finnish. 


One to closest character 


Source Source Destination Destination 
character value character value 
* 35 # 35 

$ 36 $ 36 

Q 64 Q 64 

À 91 (128 on GS) A 142 
Ó 92 (133 on GS) Ó 153 
A 93 (129 on GS) A 143 
A 94 A 94 

f 96 ` 96 

a 123 (138 on GS) i 132 
Ó 124 (154 on GS) 6 148 
à 125 (140 on GS) å 134 
~ 126 ~ 126 


ProDOS to MS-DOS: French 
This transliteration is used for French, Canadian French, and Swiss French. 


One to closest character 
Source Source Destination Destination 
character value character value 
& 35 (163 on GS)  &£& 156 
$ 36 $ 36 
à 64 (136 on GS) à 133 
* 91 (161 on GS) g 248 
ç 92 (141 on GS) ç 135 
$ 93 (164 on GS) $ 36 
^ 94 ^ 94 
i 96 j 96 
é 123 (142 on GS) é 130 
ù 124 (157 on GS) ù 151 
è 125 (143 on GS) è 138 
- 126 (1720n GS) -~ 126 
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MS-DOS to ProDOS: British English 


This transliteration is used only for British English. It is the same as the U.S. English 
MS-DOS to ProDOS transliteration except for the character listed. 
One to closest character 


Source Source 
character value 
& 156 


MS-DOS to ProDOS: Danish 


Destination 
character 


£ 


Destination 
value 


35 (156 on GS) 


One to muitiple characters 


Destination Destination 
character value 
«pound» 


This transliteration is used only for Danish. It is the same as the U.S. English MS-DOS 


to ProDOS transliteration except for the characters listed. 


Source 
value 
130 
133 
134 
138 
141 
143 
145 
146 
149 
151 
155 
156 
157 
169 
170 
224 
225 


Source 
character 


QHSLORN RO & » o 


O 
o 
3 
e 
x 


4 eot CE MIMEAZSUVHTHExtXHEQMAIRAAR: 
N 
Us 
N 


251 


One to closest character 


Destination 
character 


< *01^.49»08 FAOQOANMTZTEFADOAYMP' ' QEHaeecrAan rye Aen 


Destination 
value 

101 

97 

125 (140 on GS) 
101 

105 

$3 (129 on GS) 
123 (190 on GS) 
91 (174 on GS) 
111 

117 

124 (191 on GS) 
76 

92 (175 on GS) 
45 

45 

97 

115 

71 

112 

83 

115 

117 

116 

70 

84 

79 

100 

42 

124 (191 on GS) 
101 


One to muitiple characters 
Destination Destination 
character value 


e 


é 


125 (140 on GS) 


? 


M & Bw 


+ 


pono 


93 (129 on GS) 
123 (190 on GS) 
91 (174 on GS) 


o m N > 


e 


€ 


124 (191 on GS) 


^ 8 


pund» 
92 (175 on GS) 


1 & 


<alfa> 

SS 
<GAMMA> 
< pi> 
<SIGMA> 
<sigma> 
<my> 
<tau> 
<PHI> 
<THETA> 
<OMEGA> 
<delta> 
<uendelig> 
Ø 124 (191 on GS) 
<epsilon> 
<fzlles> 


<divideret med> 
<grader> 
* 242 
«rod» 


MS-DOS to ProDOS transiiterations E-3] 


ProDOS to MS-DOS: Spanish 


This transliteration is used only for Spanish. 


Source 
character 


OD 0 /»0. uc ow wv in 


Source 
value 


35 (163 on GS) 
36 

64 (164 on GS) 
91 (193 on GS) 
92 (132 on GS) 
93 (192 on GS) 
94 

96 

123 (161 on GS) 
124 (150 on GS) 
125 (141 on GS) 
126 


One to closest character 


Destination Destination 
character value 


£ 156 
26 
36 
173 
165 
168 
94 
96 
248 
164 
135 
126 


(e a 


im mw oF De un 


ProDOS to MS-DOS: Swedish 
This transliteration is used only for Swedish. 


i 
g 
e 


I Oaa >> OP om & 


E-28 


Source 
value 


35 

36 

64 

91 (128 on GS) 
92 (133 on GS) 
93 (129 on GS) 
94 

96 

123 (138 on GS) 
124 (154 on GS) 
125 (140 on GS) 
126 


One to closest character _ 


Destination Destination 
character value 


35 
36 
64 
142 


Le OM > WOPO y 
ms 
A 
Us 
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MS-DOS to ProDOS: French 


This transliteration is used for French, Canadian French, and Swiss French. It is the 
same as the U.S. English MS-DOS to ProDOS transliteration except for the characters 


listed. 


Source 
character 


4. 9*€ 3 UPpjEGQqamMmbheorwn » 


One to closest character 


Source Destination Destination 
vaiue character value 

133 a 64 (136 on GS) 
135 € 92 (141 on GS) 
138 è 125 (143 on GS) 
151 Ü 124 (157 on GS) 
156 & 35 (163 on GS) 
228 S 83 

229 S 115 

232 o 111 

234 U 85 

235 d 100 

236 i 42 

246 / 47 

248 re) 111 

251 - V 86 


MS-DOS to ProDOS: German 


This transliteration is used for German and Swiss German. It is the same as the U.S. 
English MS-DOS to ProDOS transliteration except for the characters listed. 


Source 
character 


Q Zed th © CEO Dim wm e 
1 
to 
~ 


249-8 +4)NE HOGI s 


One to closest character 
Source Destination Destination 
value character value 
129 ü 125 (159 on GS) 
132 á 123 (138 on GS) 
137 é 137 
142 À 91 (128 on GS) 
148 Ó 124 (154 on GS) 
153 Ó 92 (133 on GS) 
154 Ü 93 (134 on GS) 
155 c 99 
156 L 76 
164 n 110 
165 N 78 
169 - 45 
170 - 45 
225 8 126 (167 on GS) 
226 g 103 
231 t 116 
233 o 111 
234 U 85 
236 96 37 
238 ( 40 
239 U 85 
246 / 47 
247 - 45 
248 o 111 
251 V 86 


character 


One to multiple characters 
Destination Destination 
character value 

a' 

C, 

e 

u' 

«livre» 

«sigma» 

«sigma» 

«phi» 

«oméga» 

«delta» 

«infini» 

«divisé par» 

«degrés» 

«racine» 


One to multiple characters 


Destination Destination 
value 


<Cents> 
<Pfund> 
n- 
N- 


B 66 
«gamma» 
«tau» 

«theta» 
«Omega» 
«Unendlich» 
«Epsilon» 
«intersection» 
«geteilt durch» 
- 45 
«Grad» 
«Wurzel» 


MS-DOS to ProDOS transliteratlons E-33 


Source 
character 


corner 


M" 


1/2 
1/4 


Ch 4——ANHF-8)^658D5DoQG-drataneg"' 


ND <." 


E-30 


Source 
value 


169 


171 
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One to closest character 


Destination Destination 
character value 


45 
45 
50 
52 
33 
60 
62 
97 
98 
103 
112 
83 
115 
117 
116 
111 
111 
85 
100 
42 
79 
40 
85 
61 
43 
62 
60 
40 
41 
47 
45 
111 
111 
46 
86 
110 
50 


—! AN nh b 


eA COOTE ANDRA TREVA 


CO'NY~OAAVEEATO 


MD: 


One to muitiple characters 
Destination Destination 
character value 

Iz 
-| 
1/2 
1/4 
t 
<< 
>> 
a 

b 


8 
pi 


eX 


. «SIGMA» 


«sigma» 

u 117 
t 116 
«PHI» 

Q- 

«OMEGA» 
«delta» 
«infinity» 

O/ 

«epsilon» 

U 

- 61 
*- 

> = 

<a 


( 
) 
«divided by» 


«degrees» 


46 
«radical» 

^n 

^2 


MS-DOS to ProDOS: Norwegian 


This transliteration is used only for Norwegian. It is the same as the U.S. English 
MS-DOS to ProDOS transliteration except for the characters listed. 


Source Source 
character value 


155 
156 
232 
236 
238 
246 
248 
251 


4«.9*$m 3 @in 0 


One to closest character 


Destination 
character 


LONA tor 


Destination 
value 


99 
76 
111 
42 
40 
47 
111 
86 


One to muitiple characters 


Destination Destination 
character value 


«cens» 
«pund» 
«PI» 
<uendelig> 
<ypsilon> 
<delt p> 
<grader> 
<kvadratrot> 





MS-DOS to ProDOS: Spanish 


This transliteration is used only for Spanish. It is the same as the U.S. English MS-DOS 


to ProDOS transliteration except for the characters listed. 


Source Source 
character value 


135 
155 
156 
164 
165 
168 
173 
236 
246 
248 


e*$$ "7" Zi» ineo 


One to closest character 


Destination 
character 


ç 


oc 7 ^ JD inn 


Destination 
value 


125 (141 on GS) 
99 

35 (163 on GS) 
124 (150 on GS) 
92 (132 on GS) 
93 (192 on GS) 
91 (193 on GS) 
42 

47 

123 (161 on GS) 


One to multiple characters 


Destination Destination 
character value 


C, 

<centimos> 
<libra> 

n~ 

N~ 

? 63 
! 

<infinito> 
<dividido por> 
<grados> 


MS-DOS to ProDOS transliterations 


E-35 


MS-DOS to ProDOS: Dutch and Fiemish 


This transliteration is used only for Dutch and Flemish. It is the same as the U.S. 
English MS-DOS to ProDOS transliteration except for the characters listed. 


One to closest character 


Source Source 
character value 
¢ 155 

& 156 

on 236 

+ 246 

- 248 

Y 251 


MS-DOS to ProDOS: Finnish 


Destination 
character 


«0^ * Een 


Destination 
value 


99 
76 
42 
47 
111 
86 


One to muitipie characters 


Destination Destination 
character value 
<cent> 

<pond> 

<oneindig> 

<gedeeld door> 
<graden> 
<wortelteken> 


This transliteration is used for Finnish. It is the same as the U.S. English MS-DOS to 


ProDOS transliteration except for the characters listed. 


Source 
vaiue 


132 
134 
142 
143 
148 
153 
155 
156 
232 
236 
246 
248 
251 


Source 
character 


4. ot § Ohh ^ OO D Dim a 


E-32 


LON 80 FO Q0 p» p x 


One to closest character 


Destination 
character 


Destination 
value 


123 (138 an GS) 
125 (140 on GS) 
91 (128 an GS) 
93 (129 on GS) 
124 (154 on GS) 
92 (133 on GS) 
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One to multiple characters 


Destination Destination 
character value 


O” 

<sentti> 
<punta> 
«PII» 
<aareton> 
<jakomerkki> 
<aste> 
<juuri> 


Glossary 


active: For translators, one that is available for 
use. Active translators are checked in translator 
menus or, in the case of default translators, 
marked with a diamond to the left of their menu 
items to indicate that they are always active. 


activate: To make a previously unavailable 
translator available by selecting its menu item. 


Apple File Exchange document: A document 
used to store both translator settings and status 
information for translators. Users can save the 
current settings and status by selecting the Save 
Settings As menu item; they can retrieve saved 
settings by selecting the Restore Settings From 
menu item. 


Apple PC 5.25 Drive: A disk drive for Apple 
computers that can read and write MS-DOS disks. 


available: For translators, one that is contained in 
the Apple File Exchange folder. Available 
translators can appear in Apple File Exchange 
menus. 


character set: The entire set of characters that 
can be either shown on a monitor or used to code 
computer instructions. 


country code: A code that identifies the country 
for which a country-specific feature or resource is 
intended. For a complete description of country 
codes, see "The International Utilities Package" 
chapter in Volume I of /nside Macintosh. 


deactivate: To make a previously available 
translator unavailable by selecting its menu item. 


default translator: A translator that makes a bit- 
for-bit copy of a file. 


destination country: The country for which a 
transliterated file is intended. 


error message: A message displayed or printed 
to tell you of an error or problem in the execution 
of a program or in your communication with the 
system. 


file format: The internal structure of a file. 


file system: That part of an operating system that 
performs operations related to files, such as 
writing, reading, deleting, and getting 
information about files. 


file-system resource: An Apple File Exchange 
resource that provides an interface to a file system. 


file-system routine: A routine for performing a 
file-system operation. 


foreign file system: Any file system other than 
the one for the Macintosh. 


general-purpose translator: A translator that 
can convert a file format used by a wide variety of 
applications to another widely used format. 


import: To move a translator from one menu to 
another. 


inactive: For translators, one that is not available 
for use. 


Macintosh II PC Drive Card: A removable 
printed-circuit board that allows an Apple PC 5.25 
Drive to be connected to a Macintosh II. 


Macintosh Programming Workshop (MPW): A 
set of professional software development tools for 
the Macintosh. 


Macintosh SE Bus PC Drive Card: A removable 
printed-circuit board that allows an Apple PC 5.25 
Drive to be connected to a Macintosh SE. 


message: A request for an operation sent from 
Apple File Exchange to a transiator. 


MS-DOS to ProDOS: Italian 
This transliteration is used only for Italian. It is the same as the U.S. English MS-DOS 


to ProDOS transliteration except for the characters listed. 


Source 
value 


130 
133 
134 
135 
138 
141 
143 
149 
151 
155 
156 
159 
164 
165 
169 
170 
225 
226 
227 
229 
230 


Source 
character 


ZU bn 6^ O&O p» n o0 > BY 0S 


S 
3 
3 


orem E VND ONEAN TD) 
nN 
Qi 
Os 


2.8 
rm 
uA 
p 


One to closest character 


Destination Destination 
character value 


93 (142 on GS) 
123 (136 on GS) 
97 

92 (141 on GS) 
125 (143 on GS) 
126 (147 on GS) 
65 

124 (152 on GS) 
96 (157 on GS) 
99 

35 (163 on GS) 
102 

110 

78 

45 

45 

66 

71 

112 

115 

109 

116 

70 

84 

79 

100 

37 

101 

102 

106 

58 

61 

91 (161 on GS) 
111 

86 


! D "7" fn oer” ON $9 


—"0;£gnuod"nu^7"B8-ooo' 


oa” 


cO 
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One to muitipie characters 


Destination Destination 
character value 

é 93 (142 on GS) 
4 123 (136 on GS) 
3? 

ç 92 (141 on GS) 
è 125 (143 on GS) 
i 126 (147 on GS) 
A? 

Ò 124 (152 on GS) 
ù 96 (157 on GS) 
<centesimi> 

& 35 (163 on GS) 
f 

ne 

N- 

B 66 

G 71 

<p-greco> 

<sigma> 

m 109 

t 116 

<phi> 

<TETA> 

«omega» 

«DELTA» 

«infinito» 

«epsilon» 

«integrale» 

J 

s 91 (161 on GS) 
o 111 

«radice» 


A 

About boxes, designing. 2-7 

AFETrans.p | C-22-25 

Apple File Exchange documents 
3-13 

Apple PC 5.25 Drive 1-3 

Apple Programmer's and 
Developer's Association 
CAPDA) ix, x 

AppleShare File Server 1-2 

audience, remembering 2-6 


B 

British English 
Macintosh to ProDOS TProc for 
ce to ProDOS TProc for 
NECS to Macintosh TProc for 
"bos to MS-DOS TProc for 


c 


CaliErtrLog 2-20-21 
CallFS 2-4, 2-29-30 
calling conventions (external) 
A-1-5 
Calllog 2-22-24 
CallStat 2-25-26 
canceled translations 2-40 
character sets 1-2 
converting 24 
country code 2-32 
customizing icons 2-38 


Index 


Danish 
Macintosh to MS-DOS TProc for 
E-4 
Macintosh to ProDOS TProc for 
E-13 
MS-DOS to Macintosh TProc for 
E-8 
MS-DOS to ProDOS TProc for 
E-31 
ProDOS to Macintosh TProc for 
E-20 
ProDOS to MS-DOS TProc for 
E-25 
declaring translators 2-11-17 
destination country 2-32 
dialog boxes, designing 2-7 
doit C-30 
Dutch and Flemish 
Macintosh to ProDOS TProc for 
E-13 
MS-DOS to ProDOS TProc for 
E-32 
ProDOS to Macintosh TProc for 
E-20 
ProDOS to MS-DOS TProc for 
E-25 


E 

English. See British English; U.S. 
English 

error messages 2-18 

Example.a C-26 

Example, file 7 C-29 

Example.make C-31 

Example.p C-2-21 

Example.r C-27-28 

example translator C-1-31 

external calling conventions A-1-5 


F 


FFClose 

MS-DOS file system 

ProDOS file system 
FFCreate 

MS-DOS file system 

ProDOS file system 
FFDeiete 

MS-DOS file system 

ProDOS file system 
FFDirCreate 

MS-DOS file system 

ProDOS file system 
FFFlushFile 

MS-DOS file system 

ProDOS file system 
FFFlushVol 

MS-DOS file system 

ProDOS file system 
FFGetCatInfo 

MS-DOS file system 

ProDOS file system 
FFGetEOF 

MS-DOS file system 

ProDOS file system 
FFGetFinfo 

MS-DOS file system 

ProDOS file system 
FFGetFPos 

MS-DOS file system 

ProDOS file system 
FFGetVInfo 

MS-DOS file system 

ProDOS file system 
FFMakeDName 

MS-DOS file system 

ProDOS file system 
FFMakeFName 

MS-DOS file system 

ProDOS file system 
FFOKDName 

MS-DOS file system 

ProDOS file system 
FFOKFName 

MS-DOS file system 

ProDOS file system 


5-4 
4-4 


5-4 
4-4 


5-4 
5-4 
4-4 


5-4 
4-4 


5-4 
5-5-7 
4-5-6 


9-7 
4-6 


5-7-8 
4-7 


5-8 
4-7 


5-8-9 
4-7-8 


MS-DOS to ProDOS: Swedish 


This transliteration is used only for Swedish. It is the same as the U.S. English MS-DOS 
to ProDOS transliteration except for the characters listed. 


One to closest character One to muitiple characters 
Source Source Destination Destination Destination Destination 
character value character value character value 
a 132 á 123 (138 on GS) a" 
å 134 å 125 (140 on GS) aa 
A 142 A 91 (128 on GS) A" 
A 143 A 93 (129 on GS) AA 
Ó 148 6 124 (154 on GS) o" 
Ó 153 Ó 92 (133 on GS) Oo" 
€ 155 c 99 «cent» 
£ 156 L 76 <pund> 
2, 228 S 83 «sigma» 
g 229 S 115 «sigma» 
o 232 o 111 «fi» 
a 235 d 100 <delta> 
oo 236 , 42 «oándlighet» 
* 246 / 47 «dividerat med» 
: 248 O 111 <grader> 
Y 251 v 86 «rot» 
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MS-DOS to ProDOS TProcs 
British English E-31 
Danish E-31 
Dutch and Flemish E-32 
Finnish E-32 
French E-33 
German £-33 
Italian E-34 
Norwegian E-35 
Spanish E-35 
Swedish E-36 
U.S. English E-29-30 


N. O 
naming translators 2-7 
Norwegian 
Macintosh to MS-DOS TProc for 
E-5 
Macintosh to ProDOS TProc for 
E-17 
MS-DOS to Macintosh TProc for 
E-9 
MS-DOS to ProDOS TProc for 
E-35 
ProDOS to Macintosh TProc for 
E-20 
ProDOS to MS-DOS TProc for 
E-25 


P,Q 
parameters A-1-3 
for translators 2-11—-14 
Param parameter 2-13 
Pascal conventions for translators 
A-1+5 
ProDOS file system 
about 4-2 
calls 4-4-13 
calis not supported by 4-3 
limitations of 4-3 
ProDOS to Macintosh TProcs 
British English E-19 
Danish and Norwegian E-20 
Dutch and Flemish E-20 
Finnish E-21 
French E-21 
German E-22 
Italian E-22 
Spanish E-23 
Swedish E-23 
U.S. English E-19 


ProDOS to MS-DOS TProcs 
British English E-24 
Danish and Norwegian E-25 
Dutch and Flemish E-25 
Finnish E-26 
French E-26 
German E-27 
Italian E-27 
Spanish E-28 
Swedish E-28 
U.S. English E-24 

programming languages 1-4 


R 
real parameters A-3 
recognizing files 2-5 
register conventions A-5 
requirements (hardware and 
software) 1-3-4 
resources 
TProcs as 2-32 
transiators as 2-8-10 
routines (Apple File Exchange), 
calling 2-3 


$ ; 
Self parameter 2-14 
software requirements 1-4 
source country 2-32 
Spanish 
Macintosh to ProDOS TProc for 
E-17 
MS-DOS to Macintosh TProc for 
E-9 
MS-DOS to ProDOS TProc for 
E-35 
ProDOS to Macintosh TProc for 
E-23 
ProDOS to MS-DOS TProc for 
E-28 
special-purpose translators 2-6 
status flags 2-12-13 
structured parameters A-3 
Swedish 
Macintosh to ProDOS TProc for 
E-18 
MS-DOS to Macintosh TProc for 
E-9 
MS-DOS to ProDOS TProc for 
E-36 
ProDOS to Macintosh TProc for 
E-23 
ProDOS to MS-DOS TProc for 
E-28 
SYLK files, recognizing 2-5 


I 
TProc families 2-32 
structure of resources 2-33-34 
TProcs 2-4, 2-31. See also 
transliterations 
about 2-31 
relationship between Apple File 
Exchange and 2-2 
as resources 2-32 
using 2-34 
Translate 2-3 
TranslateData parameter 2-12-13 
translating files in place 2-38 
translation parameter block 2-13, 
2-14-17 
contents of 2-16-17 
type declaration for 2-15 
using for file system calls 2-28 
translations 
canceled 2-40 
examples of 2-39—40 
reporting progress of 2-24 
simple 2-39 
translator files 1-3 
translators 1-3 
about 1-3 
calls from 2-18-19, 2-27-28, 
2-31-34 
declaring 2-11-17 


general-purpose 2-9 

headers for 2-17 

naming 2-7 

parameters for 2-11-14 

Pascal conventions for A-1-5 

relationship between Apple File 
Exchange and 2-2 

as resources 2-8-10 

results returned by 2-14 

special-purpose 2-6 

tasks of 2-2-6 

user interface for, designing 
2-6-7 

Translit 2-35-37 
transliterations 1-3, 2-4. See also 

TProcs 

about 2-351 

Macintosh to MS-DOS E-1-5 

Macintosh to ProDOS E-10-18 

MS-DOS to Macintosh E-6-9 

MS-DOS to ProDOS E-29-36 

procedures 2-31 

ProDOS to Macintosh E-19-23 

ProDOS to MS-DOS E-24-28 

routines 2-31-34 


Index Il-3 


modak Refers to a dialog box in which the user 
must click a button before doing anything else. 


source country: Before a file is transliterated, the 
country for which it is intended. 

special-purpose translator: A translator that is 
used when the format of either the source or 
destination file is used by a limited range of 
applications. Nearly all translators that are not 
written by Apple are special-purpose translators. 


status flags: Bits that identify the current state of a 
translator. 


TProc: A routine for transliterating files provided 
by Apple File Exchange or another application. 


TProc family: A set of TProcs whose source 
country is the same. 

translation parameter block: A parameter 
block whose fields are used for moving 
information to and from translators. 


G-2 Glossary 


translator: A routine invoked by Apple File 
Exchange when moving files. All translators, with 
the exception of default translators, convert a file 
from one format to another. 


translator file: A resource file that contains 
translators. 


translator menu: Any of the Apple File 
Exchange menus from which users select 
translators. 


transliterate: To convert characters to equivalent 
characters in another character set. 


transliteration procedure: Any procedure, such 
as a TProc, that performs a transliteration. 


unavailable: For translators, one that is not 
contained in the Apple File Exchange folder. 
Unavailable translators cannot appear in Apple 
File Exchange menus. 


User Log: A record kept by Apple File Exchange 
of file translations and messages. 
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FPOpen 
MS-DOS file system 5-10 
ProDOS file system 4-9 
FFRead 
MS-DOS file system 5-10 
ProDOS file system 4-9 
FFRename 
MS-DOS file sysem 5-10 
ProDOS file system 4-10 
FFSetCatInfo 
MS-DOS file system 5-10-11 
ProDOS file system 4-10 
FFSetEOF, ProDOS file system 
4-10 
FPSetFInfo 
MS-DOS file system 5-11 
ProDOS file system 4-11 
FFSetFPos 
MS-DOS file system 5-11 
ProDOS file system 4-11 
FFWrite 
MS-DOS file system 5-12 
ProDOS file system 4-11 
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MS-DOS file system 5-12 
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file system; ProDOS file 
system 
calling 2-4 
calls not supported by MS-DOS 
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Flemish. See Dutch and Flemish 
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German 
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About InterFile 


[nterFile is a tool which allows a user to transfer files and directories from one disk to another, 
even if the disks belong to different file systems. For instance, even though the Macintosh disk 
drive can read the 3.5" disks used by the Apple II family, it can't quite interpret them. In a sense, 
it's like someone who only understands English trying to read a Swedish sentence (like "Små 
grádorna dr lustiga att se"); we can read off the letters but can't interpret the words they signify. 
[nterFile acts like an interpreter between these "foreign" disks and the Macintosh disks, allowing 
the user to select files on either disk and copy them across. 


In addition to copying files to and from foreign disks, InterFile can provide a list of possible 
"conversions" to be applied to the file as it is copied. For instance, an AppleWorks™ word 
processing file isn't worth much on the Macintosh if it is copied straight across, but if it is 
converted in the process into a MacWnite file, then we can really do things to it. InterFile will 
allow a user to select from an ever-growing "library" of conversions. 


A note about terminology: If you are among those who have used earlier versions of 
InterFile, you'll have noticed the new name of the product; it was previously known as Passport. 
In addition, note that the "visa" files described in earlier documents are now called translators. 


About this document 


These Preliminary Notes contain five parts: 


* Part 1 is a user's guide for InterFile. It contains a preliminary draft of two chapters from the 
forthcoming Macintosh Utilities Guide. These chapters are subject to change. 


* Part 2, "Conversion Routines for InterFile," tells how to write new routines to convert files of 
one type to another. 


* Part 3, "Using ProDOS From InterFile Conversion Routines," tells how programmers can use 
the ProDOS foreign file system provided with InterFile. 


* Part 4, "Using MS-DOS From InterFile Conversion Routines," tells how programmers can use 
the MS-DOS foreign file system for the IBM® PC and compatible computers that is provided with 
InterFile. 


¢ Part 5, "The MacUnary File Format," describes a file format for storing Macintosh files on other 
file systems. 


This documentation does not constitute a manual and should not be considered complete in its 
present form. While every attempt has been made to verify the accuracy of the information 
presented, it is subject to change without notice. The primary reason for releasing preliminary 
product information is to provide the development community with essential product specifications, 
theory, and application information at the beginning of the manual development process in order to 
stimulate work on compatible third-party products. 


— 
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Part 1: InterFile User's Guide 
InterFile Preliminary Notes 


Part 1: 
InterFile User's Guide 


How to use the file transfer facilities provide by 
InterFile, Version 1.0 


The following is a preliminary draft of two chapters from the forthcoming Macintosh Utilities 
Guide. This documentation does not constitute a manual and should not be considered complete in 


its present form. While every attempt has been made to verify the accuracy of the information 
presented, it is subject to change without notice. 
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Apple, AppleLink, and ProDOS are registered trademarks and AppleWorks and Macintosh are trademarks of Apple 
Computer, Inc. 

Excel, Microsoft, and MS are registered trademarks of Microsoft Corporation. 

[BM is a registered trademark of International Business Machines Corporation. 

VisiCalc is a registered trademark of Software Arts Productions, Inc. 


MS-DOS stands for Microsoft 
Disk Operating System. ProDOS 
stands for Professional Disk 
Operating System. An operating 
system is a program that 
organizes the actions of the 
parts of the computer and its 
peripheral devices. MS-DOS is 
the operating system that 
governs the IBM PC and its 
copies. ProDOS is the operating 
system that today controls 
most Appie Il computers. 
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Introduction to InterFile 


InterFile is an Macintosh application that allows you to 
work with documents created on MS-DOS and 
ProDOS personal computers. And it allows anyone 
with an MS-DOS or ProDOS computer to work with 
documents that you've created on your Macintosh. 


If you've been working with people who use 
computers controlled by other operating systems, 
you know that the world of computing is like the 
Biblical Tower of Babel. It is difficult, sometimes 
impossible, to get your computers to work together, 
because the machines speak different "languages." 


With InterFile, however, you can translate files so they 
make sense when you transfer them between 
computers. Then you and your associates can work 
together more effectively, whether you are building a 
tower or just trying to run an office. 


This chapter describes the essential features of 
InterFile. To learn more about the many things you 
can do with InterFile, see Chapter 8, “InterFile: 
Advanced Features." 





You need InterFile if... 


InterFile is designed to meet a variety of translation 
needs. You need InterFile if: 


o You have a Dorothy disk drive and want to transfer 
documents between your Macintosh and an MS-DOS 
computer. 
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Part 2: Conversion Routines for InterFile 


About InterFile and conversion routines 2-2 
Audience 2-2 
Conversion resources 2-2 
Conversion menus 2-4 
Conversion parameter block 2-5 
Conversion routines 2-7 
Headers for conversion routines 2-8 
The Init routine 2-9 
The Finis routine 2-9 
The Get Status routine 2-10 
The Set Status routine 2-11 
The Activate routine 2-11 
The Inactivate routine 2-12 
The Appear routine 2-12 
The Disappear routine 2-13 
The Recognize routine 2-13 
The NewName routine 2-14 
The Convert File routine 2-15 
The Load routine 2-16 
The About routine 2-16 
The Get Default routine 2-16 
The Set Default routine 2-16 
Importing conversions 2-17 
How files get converted 2-17 
Calling the file systems 2-19 
Skeleton conversion routine 2-21 


Part 3: Using ProDOS® From InterFile Conversion Routines 


About InterFile and ProDOS 3-1 
General limintations for ProDOS routines 3-2 
About the MacUnary file format 3-2 

ProDOS calls from InterFile 3-3 





What you need 


InterFile runs on any Macintosh computer that 
contains at least 512K bytes of random access memory 
(RAM). 


Since you probably want to use InterFile to copy files 
from one disk to another, InterFile works best when 
your Macintosh has two or more internal or external 
disk drives. Otherwise, you may be stuck inserting and 
pe disks repeatedly every time you translate a 
ile. 


If you are planning to work with 5.25-inch MS-DOS 
disks, one of those disk drives should be a Dorothy. 





The InterFile folder | 


InterFile appears as a folder on your Utilities disk. 
Before you use InterFile, it makes sense to copy the 
entire folder to a hard disk or another 3.5-inch disk 
with more space available. 


Open the folder, and you'll see the InterFile 
application and one other file, called a translator file. 
Each translator file contains the information that 
InterFile needs to translate documents between two 
application programs. 


ART 7-2 


Figure 7-2 
The InterFile folder on the Ufilifies disk 


~~ 
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Part 4: InterFile and MS-DOS 
InterFile Preliminary Notes 


Part 4: 
Using MS-DOS From InterFile Conversion 


Routines 


How to use the MS-DOS routines 
provided with InterFile, Version 1.0 


This part contains information on the implementation of the MS-DOS routines that come with 
[nterFile. 


Before reading this part, you have some familiarity with InterFile, be familiar with its operation as 
described in Part 1, and have read the Part 2 of the Preliminary Notes, “Conversion Routines for 
InterFile." You should also be familiar with /nside Macintosh, in particular "The Resource 
Manager" chapter in Volume I and "The File Manager" chapter in Volume IV. 


About InterFile and MS-DOS 


InterFile is a tool which allows a user to transfer files and directories from one disk to another, 
even if the disks belong to different file systems. When a file is copied from one file system to 
another, a conversion routine changes the form of the data from one representation to another. This 
conversion routine has full control over the process of reading the source file and writing the 
destination file; it makes calls to the different file systems through a common interface described in 
Part 2 of the Preliminary Notes, "Conversion Routines for InterFile." 


MS-DOS is Microsoft's disk operating system for the IBM PC and compatible computers. 

InterFile supports versions of MS-DOS numbered 2.0 and higher. The data structures used by 
these versions provide a hierarchical, tree-structured file system similar to the Macintosh 
hierarchical file system (HFS). However, there are significant differences in the overall philosophy 
of file management (besides the obvious differences in file storage) between MS-DOS and HFS. 
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supplemental reference documents 


Other development tools are available through membership in APDA (Apple Programmer's and 
Developer's Association). For further information, you can contact APDA by writing to them at 
290 SW 43rd Street, Renton WA, 98055 or calling (206) 251-6548. 


Part 4: InterFile and MS-DOS 


FFGetFInfo 


The following fields return zero: 


ioFlFndrinfo 
fdLocation 
fdFldr 

ioFIStBIk 

ioFIRStBik 


The following fields return values: 


ioNamePtr - if file specified by ioFDirIndex 
ioFRefNumber - file reference number if the file is open 
ioF LAttrib - file attributes - reflects some of MS-DOS characteristic bits 

$01 - if file locked (read-only bit set) 

$04 - if resource fork is open (MacUnary files only) 

$08 - if data fork is open 

$40 - if file is in MacUnary format 

$80 - if either fork is open 

all other bits clear 
ioFIFndrInfo 

fdtype 
TEXT - if the file is calculated to be a text file (see next section) 
ZSYS - if the system file bit is set 
BINA - all other files 

fdcreator - 'mdos 

fdFlags 

$4000 - if file is invisible (Hidden file bit is set) 
all other bits clear 

ioDirID - file number 
ioFILgLen - data fork logical length 
ioFIPyLen - data fork physical length 
ioFIRLgLen - resource fork logical length (if MacUnary format) 
ioFIRPyLen - resource fork logical length (if MacUnary format) 
ioFiCrDat - creation date 
jioFIMdDat - same as creation date 


How to recognize MS-DOS text files 


iv 


Lae 


Read the first 1024 bytes of the file (or all of the file if it is less than 1K). 

Count the number of printable characters (space through tilde) versus the number of non-printables (all others, 
including high-bit-set characters). 

If the number of printable characters is at least twice the number of non-printables, then the file is most likely 
a text file. 


Because this algorithm is not foolproof, a conversion routine should not depend on the file being a text file just 
because it has the file type 'TEXT.' The file type does, however, give an indication as to the likelihood of a file 
containing ASCII text. 
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Chapter 7 


InterFile 
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Part 4: InterFile and MS-DOS 


FFSetCatInfo 
The following fields are ignored for files: 
ioFIFndrInfo 
fdLocation 
fdFldr 
ioFIXFndrInfo 
ioFIClpSiz 
:oFlCrDat 


The following fields may be set for files: 
ioFlAturib 
$01 - to lock file 
$40 - to force MacUnary format 
all other bits ignored 
NOTE - If the MacUnary bit is set for a file that is not in 
MacUnary format, it forces the file to be MacUnary. If 
the MacUnary bit is cleared for a file that is in MacUnary 
format, this call reverts it to normal format if the file 
type and creator are legal and the resource fork is empty; 
otherwise this call fails. 
ioFIFndrInfo 
fdtype - | 
the following file types are ignored: 
TEXT, 'BINA , 'ZSYS' (this one sets the System bit), 
all nulis 
all other file types forces file to be MacUnary format 
fdcreator - 'mdos' or all nulls (same as 'mdos) 
anything else forces file to be MacUnary format 
fdFlags - reflects the "Hidden file" bit 
$4000 - if file is invisible 
all other bits ignored 
ioFIMdDat - modification date 
ioFIBkDat - if less than the modification date, sets Changed access 
bit, otherwise ignored. 


The following fields are ignored for directories: 
ioDrUsrWds 
ioDrFndrinfo 
ioDrCrDat 
ioDrMdDat 
ioDrBkDat 


The following fields can be set for directories: 
ioNamePtr - if directory specified by ioFDir[ndex 
ioFlAttrib - dir attributes—reflects some of MS-DOS access bits 
$01 - if dir locked ($02 access bit clear) 
all other bits ignored 
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When connected fo your 
Macintosh. Aladdin or Beck's, the 
Dorothy exchanges information 
oetween the Macintosh and 

5 25-nch disks formatted 
(imtialized) with MS-OOS. 


Macintosh with InterFile 
MS-DOS computer 
| Dorothy Drive 


Apple | 


InterFile Preliminary Notes 


O You are working with an Apple II computer, such as 
an Apple IIGs, that uses 3.5-inch disks, and you want 
to transfer documents between your Macintosh and 
the Apple H. 


ART 7-1 


Figure 7-1 
Exchanging Information with both MS-DOS and ProDOS (Apple 
i) computers 


O You are using a telephone line, network, or other 
connection to transfer files between your Macintosh 
and an MS-DOS or ProDOS computer, and you want 
to translate those files. 
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Part $: The MacUnary File Format 
InterFile Preliminary Notes 


Part 5: 
The MacUnary File Format 


Storing Arbitrary Macintosh Files in a 
Single Data Stream 


The following is a proposal for storing arbitrary Macintosh files as a single stream of data suitable 
for most file systems. Because the format "flattens" the Macintosh file structure into a single data 
fork and because its heritage is from the MacBinary format, the format proposed herein is called 
the "MacUnary" format. 


The format consists of a header containing all the information necessary to reproduce the 
document's directory entry from the Macintosh, followed by the data fork (if it has one), followed 
by the resource fork (if it has one). The lengths of these individual forks (either of which may be 
zero) is stored in the header, along with any padding information. 


The end of the header and the two file forks can be padded out with zeros, as indicated by 
information in the header. This allows whichever storage mechanism (program, file system) that is 
in charge of creating, updating, and removing the file to choose a padding which optimizes the 
operations on the file. For instance, if a file system chooses to pad out to the nearest block 
boundary, then random calls to extend the data and resource forks can be interleaved and the file 
can "straighten out" the file upon closing by rearranging its block allocation table. 


The format of the header is listed below with the following explanations: 1) offsets and lengths are 
given in decimal, except when preceded by a dollar sign "$" to indicate hexadecimal, 2) all words 
and long words are stored with the most significant byte first. 


Offset Length Contents 
0 1 $80 - to indicate a different version from MacBinary 
] 1 Length of original Macintosh file name 
2 63 Filename (only "length" bytes are significant) 
65 4 File type* 
69 4 File creator* 
73 2 Finder flags* 
13 2 File's vertical position in its window. * 
77 2 File's horizontal position in its window.* 
79 Z File's window or folder ID* 
81 ] File's attributes 
Bit 0 - Locked Bit 6 -Protected 
82 l $00 
83 4 Data fork length 
87 4 Resource fork length 
91 4 File's creation date 
95 4 File's last modification date 
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The translator file In your 
interFite folder is labeled DCA, 
which stands for Document 
Content Architecture. Many 
MS-DOS word processing 
applications, sucn os 
Dispiaywrite 3, allow users fo 
save their documents as DCA 
files. This file atlows InterFile to 
convert DCA files to MacWrite, 
and vice versa. 


A text file contains information 
stored in the form of readable 
characters and encoded using 
the ASCII format. 


InterFile Preliminary Notes 


You'll probably want to add translator files to your 
InterFile folder, so you can translate files to or from a 
variety of MS-DOS or ProDOS applications. (See 
"Obtaining Translator Files," later in this section.) 


ART 7-3 


Figure7-3 
An InterFile folder with added translator files 


For example, if you add the translator file Wordstar to 
your InterFile folder, as shown in Figure 7-3, you can 
use InterFile to convert documents that were written 
with Wordstar, a popular MS-DOS word processing 
application, into MacWrite documents, or vice versa. 


In addition to the translator files that you see in the 

InterFile folder, the InterFile application itself contains 

two translator files: 

D The text translator file allows InterFile to exchange 
text files with both MS-DOS and ProDOS 
computers. 
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All computer filles can be 
represented in binary code.. in 
wnich information is 
represented by the l's and O's 
of the binary number system. 


InterF ile Preliminary Notes 


o The binary translator file allows InterFile to copy any 
file, in binary form, to and from both MS-DOS and 
ProDOS computers. 


Once you open IntetFile, you'll be able to select the 
translators you want from menus corresponding to the 
operating systems that you're working with, such as 
*MS-DOS to Mac" or *Mac to ProDOS." 


Obtaining translator files 


You should be able to buy a variety of InterFile 
translators from your authorized Apple dealer or 
representative, as well as many other suppliers of 
computer software. The translator files—other than 
DCA—shown in Figure 7-2 are all products of Dataviz, 
Inc. corporation. 


Three ways to use InterFile 


If you're using InterFile, one of the three following 
situations applies to you: 


o You know which files you want to translate, and you 
know which translators you want to use. This is the 
simplest way to use InterFile, and it is described in 
this chapter. 


o You know which files you want to translate, but you 
don't know which translators you want to use. You 
need to know a little bit more about InterFile, so 
this situation is described "Letting InterFile Select the 
Translators," in Chapter 8. 


D You know which translators you want to use, but 
you don't know which files you want to translate. 
Though this may be the way that you usually use 
InterFile, it involves extra steps. This situation is 
discussed in "Letting InterFile Help Select the Source 
Files," also in Chapter 8." 
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Part 4: InterFile and MS-DOS 


FFSetVInfo 
The following are ignored: 

ioVClpSiz 
ioV SeqNum 
ioVFndrinfo 
i0 V Atrb 
ioVCrDate 
ioVI sMod 
ioVBkUp 


This call is really only good for renaming a volume. 


FFOpenRF 
Will open resource fork on all files. If the program subsequently 
issues a write call (FF Write) to this fork, it forces the file 
to be converted to the MacUnary format. 


FF Write 
For data forks, works the same as on the Macintosh. For resource forks, 
if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. 


FFSetEOF 
For data forks, works the same as on the Macintosh. For resource forks, 


if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. 


FFAllocate 
For data forks, works the same as on the Macintosh. For resource forks, 
if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. 


FF AllocContig 
For data forks, works the same as on the Macintosh. For resource forks, 
if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. 


FF Create 
Creates a regular file (not MacUnary). To set the type, you 
must issue a FFSetFInfo or FFSetCatInfo call, which may force 
the file into MacUnary format. 
If the name of the file created does not conform to MS-DOS conventions, 
the FFCreate call will fail for "Bad file name" error. 
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Folder 
Application 

 . Document 

Text document 


System file 


InterFile treats MS-DOS 
ditectorles and ProDOS sub- 
directories as folders. 


InterFile Preliminary Notes 


ART 7-4 
Figure 7-4 
The control dialog box. when InterFile is opened 
An icon to the left of each file tells you what it is. 


ART 7-5 


Figure 7-5 
icons Identifying files and folders 


SS RM MM———— 
Selecting source files 

The documents and other files that InterFile translates 
are called source files. You can select source files 


individually or in groups. You can also select all the 
files in a folder by selecting the folder. 
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Part 4: InterFile and MS-DOS 


When reading a file using InterFile, it is often useful to be able to recognize it as an MS-DOS file (remember that 
your conversion may be imported to a different menu—say "Mac to Mac"—even though it is “expecting” to deal 
with an MS-DOS volume). Listed below are a number of qualifying and disqualifying criteria. 


Disqualifving Criteri 


Non-zero Resource Fork - The biggest disqualifying criterion is the presence of a resource fork. Although a resource 
fork doesn't prevent a program from treating the rest of the file as a standard MS-DOS file, it is obvious that 
no unmodified MS-DOS file would be stored on the Macintosh with a resource fork. 


File Type and Creator - If the file type indicates that the file is an application (in which case it has already been 
disqualified by the resource fork), or that it is a standard document from some other application (say, a 
"TEXT file from MacTerminal! or MPW), then the file probably didn't originate on MS-DOS. 


File Name - If the file name doesn't follow the standard MS-DOS file naming conventions, it may not have 
originated on MS-DOS. This is a fairly weak criterion, because the user may have changed the name after il 
came across to the Macintosh. 


E lif * C * * 


File Contents - The strongest qualifying criterion is the actual contents of the file's data fork. If the contents can be 
recognized as a WordStar file, a Lotus file, or some other native file from MS-DOS, then you're in business. 
This is usually impractical, however. 


File Creator - A good indication is if the fdCreator field of the ioFIFndrInfo record is ‘mdos’. 


File Type - The fdType field of the ioFiFndrInfo record is ‘BINA’, "TEXT, or "ZSYS'. This is a fairly weak 
criterium since many terminal programs bring MS-DOS files across with no type at all. 


File Name Extension - The file name follows the MS-DOS file naming conventions and has an extension that 
indicates one of the (de facto) standard MS-DOS extensions. Remember, the user could have changed this 
name in the Finder. 


FFSetFInfo 
The following fields are ignored: 
ioFIFndrInfo 
fdLocation 
fdFldr 
ioFlCrDat 


The following fields may be set: 
ioFIFndrInfo 
fdtype - 
the following file types are ignored: 
"TEXT, 'BINA ,' 'ZSYS' (this one sets the System bit), 
all nulls 
all other file types force file to be MacUnary format. 
fdcreator - 'mdos' or all nulls (same as ‘mdos’) 
anything else forces file to be MacUnary format 
fdFlags - reflects the "Hidden file" bit 
$4000 - if file is invisible 
all other bits ignored 
ioFIMdDat - modification date 
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InterFile Preliminary Notes 


% Note: When using InterFile, you may run into a 
situation that does not occur in most other 
Macintosh applications. You might select the entire 
contents of a disk or folder, and then decide to 
remove the selection. Since there is no unselected 
item to click, it may not be obvious how to de- 
select. 


There are three simple ways. First, you can select a 
file in the other directory—if one is shown—in the 
control dialog box. Second, you can type any 
keyboard character. And third, you can de-select a 
single item by clicking it while holding down the 
Apple (Command) key. 


ee 
>Á ———Vw_e 


Selecting destination directories 


Files that have been translated are called destination 
files, and InterFile places them in destination 
directories, which can represent either folders or the 
disk itself. You can select existing folders Cor the disk), 
or you can create a new folder as the destination for 
your translated files. 


Selecting a destination directory is essentially the same 
as displaying a folder containing source files: 
1. Insert another disk or click Drive to show the destination 
disk in the second directory. 
|. |f you want to place the translated files the disk-level 
directory, skip the following steps. 


2. Open folders until the folder you want to receive 
translated files is shown as the directory name at the top. 


3. If necessary, press and drag on the directory name to 
move back down toward the disk directory. 


To create a new destination folder 


1. Moke sure that the name of the second directory 
represents the folder or disk where you want to place the 
new folder. 


2. Click the New Folder button below the directory. 
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Part 4: interFile and MS-DOS 


ioDrBkDat 
The following fields return values for directories: 
ioNamePrr - if directory specified by ioFDirindex 
ioFlAttrib - dir attributes 
$01 - if dir locked 
$10 - always set (indicates directory) 
$20 - if directory allows subdirectory (usually set) 
all other bits clear 
NOTE: The Macintosh does not support recognition of bit $20 
as described above—it is included for support of InterFile 
ioDrDirID - directory ID (root is indicated by 2) 
ioDrNmF Is - number of files and directories in this directory 
ioDrParID - ID of parent of specified file (2 indicates root, 0 
indicates no parent, that is, we're already talking about the 
root and we can't go any higher) 


The PBGetCatInfo call is perhaps the strangest routine in the ROM. It is also one of the most powerful, so you 
have to put up with it. In case you have difficulty understanding how it works, here is a short summary: 


ioFDirIndex = n (> 0) 
INPUT 
ioNamePtr - ignored 
ioDirID - if 0, use ioVRefNum for volume and directory, else use ioDirID for directory 
OUTPUT 
ioNamePtr^ - returns name of nth file or directory 
ioDirID - returns file number (ioFINum) or directory number (ioDrDirID) 
ioFIParID - returns directory number of parent of nth file or directory 


ioFDirIndex = 0 
INPUT 
ioNamePrr^ - contains name of file in question (error if ioNamePu = NIL) 
ioDirID - if 0, use ioVRefNum for volume and directory, else use ioDirID for directory 
OUTPUT 
ioNamePt^ - unchanged 
ioDirID - retums file number (ioFINum) or directory number (ioDrDirID) 
ioFIParID - returns directory number of parent of file or directory in question 


ioFDirIndex = -1 
INPUT 
ioNamePtr - ignored 
ioDirID - if 0, use ioVRefNum for volume and directory, else use ioDirID for directory 
OUTPUT 
ioNamePtr^ - returns name of directory specified by ioVRefNum and ioDirID 
ioDirID - returns number of directory (ioDrDirID) specified by ioVRefNum and ioDirID 
ioFIParID - returns directory number of parent of directory in question 
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Most transiator files contain 
"gnstators for taking a 
*transiation in both directions. 
That is, the DCA translator file 
contains a translator for “DCA 
*o MacwWrite” and one for 
"MacWirite to DCA.” 


One menu item, Ofher 
conversions. is not actually a 
translator, but a command that 
you use to call upon conversions 
not shown in the menu. See 
“Translating Files That You've 
Already Copied.” in Chapter 8. 


As shipped 


With additional translators 


interFile Preliminary Notes 


€ Note: InterFile is capable of translating files 
between the two non-Macintosh operating systems. 
Thus, it is possible to show menus for “MS-DOS to 
ProDOS" and "ProDOS to MS-DOS." 


Each InterFile translation menu lists the translators, 
from the InterFile folder, appropriate to that menu. 
Thus, the "MS-Dos to Mac" menu shows the translators 
for “DCA to MacWrite,” "Text," and "Binary." 


If you've copied into the InterFile folder other 
translators capable of converting files created with MS- 
DOS applications files into Macintosh documents, they 
are listed alphabetically, along with "DCA to 
MacWrite," above the dotted line. 


Text and binary translations always appear below the 
dotted line. 
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Part 4: InterFile and MS-DOS 


The following calls behave as they do on the Macintosh with no difference: 


FFFlushVol 
FFOpen 
FFLockRange 
FFUnLockRange 
FFRead 
FFWrite 
FFGetFPos 
FFSetFPos 
FFGetEOF 
FFFlushFile 
FFClose 
FFDelete 
FFSetFLock 
FFRstFLock 


The following calls are not supported for MS-DOS: 


FFOpenWD 
FFCloseWD 
FFGetWDInfo 


The MacUnary format (see Part 5) is fully supported by the MS-DOS foreign file system with an 
internal clump size equal to the volume cluster size for the data and resource forks, and a header 


size also equal to the volume cluster size. 
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Figure 7-9 
Selecting the transiator “AppleWorks to Works” in a typical 
"ProDOS to Mac” menu 


2. If any translator that you don't want is checked, uncheck it 
by dragging down to the menu item and releasing the 
mouse button. 


4 Note: To learn more about specific translators, 
choose About InterFile from the Apple menu. The 
About InterFile window contains a list of 
translators. Select one translator, and then click the 
About button to display a description of that 
translator. The window shown in Figure 7-10 
corresponds to the folder shown in Figure 7-5. 


ART 7-10 


Figure 7-10 
The About InterFlle window 
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Part 5: The MacUnary File Format 


> 
File's backup date 


99 4 
103 16 File's extended Finder information 
119 2 File's clump size 
121 2 Number of total bytes in header 
123 2 Number of pad bytes for data fork 
125 2 Number of pad bytes for resource fork 
127 l $00 


* This data comes from the standard Finder Info record. 


Note that the MacUnary header is initially identical to the MacBinary header except for bytes 0 and 
81; at byte 99 the MacUnary header starts listing information not included in the MacBinary 
header. The minimum header size is 128 bytes, and can be longer as indicated by the value at byte 
121. If the header is listed as being longer than 128 bytes, the following information is valid: 


Offset Length Contents 
128 l $80 - to indicate extended header information 
129 2 Internal clump size for data fork 
131 2 Internal clump size for resource fork 
133 16 Internal scratch data 
149 1 00 
150 l Length of Get Info information 
135 105 Zeros - for expansion of standard 


If the length of the Get Info information is non-zero, and the length of the header can hold it, the 
Get Info string starts at offset 256 and can be up to 255 characters in length (the length byte is not 
repeated for the string); the final byte is zero. A full header is thus 512 bytes long. 


The internal clump size for the data and resource forks is used as a suggestion to maintain 
consistent padding at the end of those forks. For instance, the padding information (when added 
to the logical length) may indicate the data fork ends on a 2K-byte boundary, but when more 
information is added, do we maintain a 2K-, 1K- or 512-byte boundary? The clump size, if non- 
zero, can help in this internal maintenance. 
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InterFile Preliminary Notes 


cj insert or switch drives to another destination disk. 


o select unneeded files on the destination disk and 
click Remove to delete them. 





To translate files 
1. Click the Translate button. 


If the names of destination files or folders conflict 
with existing files or folders, or with each other, 
InterFile warns you and allows you to change the 
destination names. (See “When Filenames Conflict,” 
in Chapter 8 of this guide.) 


InterFile displays the progress window, shown in 
Figure 7-12. 


ART 7-12 


Figure 7-12 
The progress window 


The progress window shows, as each file is 
translated, the source filename, the destination 
filename, and the type of translation. The horizontal 
thermometer reports, for each file, what percentage 
of the current translation is complete. Entries at the 
bottom of the window tell how many files you 
selected and how many files have been translated. 
The progress window reports when InterFile is done 
copying files. 


If you click Cancel, translation is halted at once. Files 
that have already been translated remain in the 
destination directory. 
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Getting started 


No matter how many files you plan to translate, or 
how many translators you expect to use, you follow six 
basic steps to translate files with InterFile: 


C You first open the InterFile application. 
o You then select the files you want to translate. 


O Next, you select or create a folder to receive the 
translated files. 


o You choose the translator(s) you wish to use. 
O Then you translate the files. 


o Finally, you close InterFile and begin working with 
the translated files. 


To open InterFile 
1. Open the interFile folder. 


2. If you have obtained other translators, drag them into the 
folder. 


3. Open the InterFile application. 


The InterFile control dialog box appears. InterFile 
presents a new menu, "Mac to Mac," on the menu 
bar. The directory on the left lists files and folders 
on the disk containing InterFile. As shown in Figure 
2 the directory name and disk name are identical 
at first. 


Directory name 
Directory 
Disk Name 


Space availabie on disk 
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Chapter 8 


InterFile: 
Advanced Features 
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The Apple key and the 
Command key are the some 
«ey. If your keyboard does not 
nave a key with an Apple 


symbol. use the Command key, 


which has a propeller-shaped 
symbol. 
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Figure 7-6 
The flle News.Jan, In the folder Newslett on fhe MS-DOS disk 
Pubs. is selected 


To select more than one file or folder 


Use the first method to select any collection of files 
x folders. Use the second to select adjacent files and 
olders. 


E Hold down the Apple (Command) key and click the files 
or folders you wish to select. 


All files that you click remain selected. 


m Hold down the Shift key and click the first and last files or 
folders. 


Those two files or folders, and all of those in 
between, are selected. | 


3-5-87 Page 1-12 


The default is a preset response 
that is automatically used if you 
aon't supply a different 
response. 
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Figure 8-1 
Preparing a menu so InterFlle can select translations 


When you click Translate, InterFile automatically uses 
the proper translator for each file. 


If you have selected any source files that were created 
by applications that are not handled by one of your 
translators, those files are translated by the default 
translations, Text and Binary. 


With Macintosh and ProDOS documents, InterFile 
selects the Text translator only if the document have 
been saved as text files—that is, “text only” on the 
Macintosh and “.txt” on the Apple II. 


With MS-DOS files, InterFile selects the Text translator 
if most of the characters in the files are readable 
keyboard characters. 


If no other translator is capable of transfering a file 
from one operating system to another, InterFile makes 
a copy, in binary code. If you use the Binary translator 
to copy an MS-DOS and ProDOS file to your Macintosh 
disk, you may later be able obtain translators to 
convert the file into a useful document. (See 
"Translating Files That You've Already Copied," later in 
this chapter.) 
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InterFile presents the following dialog box. 
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Figure 7-7 
The dialog box for naming a new folder 


3. Type a name for the new folder. 
InterFile rejects folder names that are too long or 
that contain characters or sequences not acceptable 
in the disk's operating system. 
Use the mouse and keyboard to edit the folder 
name. 


4. Click OK. 


LL———— MM ————— 


Selecting translators 


Whenever you show an MS-DOS or ProDOS disk in 
the control dialog box, InterFile's "Mac to Mac" menu 
is replaced by two menus. InterFile takes the | 
operating system of the disk shown on the left, adds 
the word to, and then the operating system of the disk 
shown on the right. The second, or right menu is the 
exact opposite. 


Thus, when the disk shown on the left is MS-DOS and 
the disk shown on the right in a Macintosh disk, 
InterFile shows menus for “MS-DOS to Mac" and “Mac 
to MS-DOS.” 
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InterFile Preliminary Notes 
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Figure 8-2 
Ellgible flles are not dimmed 


5. In the directory representing your source disk, select ali 
files and folders that are not dimmed. 
When you select folders that contain both eligible 
and ineligible files, InterFile will translate only the 
eligible files, as long as the Show Eligible Files 
command is checked. 


4 Note: The Show Eligible Files command does not 
show as eligible those files that can be translated 
only with the Text or Binary translators. 


6. Continue by clicking the Translate button. 
See Translating Files, in Chapter 7. 








Translating Files That You've Already 
Copied 

Thus far, you have learned how to use InterFile to 
exchange files between your Macintosh and MS-DOS or 
ProDOS disks. You can also use InterFile to translate 
MS-DOS and ProDOS files that are already on one of 
your Macintosh disks, but which cannot be “read” by 
Macintosh applications—except InterFile. 


You may have obtained those untranslated files in 
many ways: via a telephone line, over a network, or 
even by using InterFile’s default Binary translator. 


To translate non-Macintosh files that are stored on 
Macintosh disks, follow these steps. 
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ART 7-8 


Figure 7-8 
Two versions of the “MS-DOS to Mac” menu 


To select the translators you want 


InterFile calls upon a translator only if it is selected in 
the proper menu. Selected translators are shown with 
check marks. The diamond symbol indicates that 
binary translation is always selected. 

1. .if any translator that you want is unchecked, select it by 
dragging down to the menu item and releasing the 
mouse button. 

With many translators, InterFile presents a 
conversion options dialog box. (See “Setting 
Options" in Chapter 8). You can use the preset 
options simply by clicking OK. 
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4 Note: You can use the same procedure to add 
conversions to any InterFile menu. 


ART 8-4 


Figure 8-4 
The "Mac to Mac” menu with other conversions added 
4. Select ihe translators that you want to use. 
5. Click the Translate button. 
See Translating Files, in Chapter 7. 








Resolving filename conflicts 


In using InterFile, you may run into any one of the 
three following situations in which destination 
filenames conflict with other file and folder names. In 
each situation, you see an alert box after you click 
Translate. 


C) A destination file has the same name as an existing 
file Cor a destination folder has the same name as an 
existing folder) in the destination directory. 

An alert box allows you to click the Rename button 
to display a window in which you can create a new 
name for the destination file or folder. You can also 
replace the existing file Cor folder) with the new 
translation, or you can cancel the translation. 
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Source disk 

Source directory 

Source file 

Destination disk 

Destination directory 

Active menu 

Selected transiator 

Soace available in destination disk 


Space selected (size of source flle) 


The soace selected actually 
gives you only a rough idea of 
‘ne space that the tronsated 
‘les will take up. since 
translations frequently alter the 
‘ength of files. 
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Translating files 


Now you are almost ready to translate your files. Figure 
7-11 shows the control dialog box set up to translate 
one DCA file, News.Jan, into a MacWrite document. 
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Figure 7-11 
Ready to translate the DCA flle News.Jan to MacWrfte and 
transfer It to the Macintosh folder Newsletters 


First, however, you should compare the space 
selected, as shown in the center of the InterFile dialog 
box, with the space available in the destination disk. 


If there is not enough space, you can do any of the 
following: 


C de-select some of your source files. 
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Source directory 
Source disk 
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Figure 8-5 | 
A typical Rename window 


This window lists the source files and folders that you 
selected in the control dialog box. You can scroll the 
list, open folders, and move toward the disk directory 
using the techniques described in your Macintosh 
owner's guide. 


For each file or folder, there is space for a symbol 
identifying a naming conflict. 


To the right of each source file or folder name, the 
corresponding destination file and folder names are 
displayed. The source and destination names are 
scrolled together. 


When you first activate the Rename window, the 
destination name is the source name or a slightly 
altered or truncated version. To change destination 
names, follow these steps. 


1. Select any destination filename. 


You can select the next destination filename on the 
list by pressing the Tab key, and you can select the 
previous listing by holding down the Apple 
(Command) key while pressing the Tab key. 


2. You can edit the seiected destination filename by using 
your mouse and keyboard in the standard Macintosh 
fashion. 


3. Click Transiate to confirm your changes and close the 
window if you entered it from one of the alert boxes. 


This restarts the translation process, using the new 
destination filenames. 
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2. Click Done to return to the InterFile control dialog box. 


Finishing up 


Once you have completed a translation, you can start 
setting up another one, or you can quit InterFile. 


E Choose Quit from the File menu, or click the close box in 
thecontrol diallog box, to retum to the Finder. 


Whenever you quit InterFile, non-Macintosh disks 
are ejected automatically. 


Once you have translated your files, it makes sense to 
open them—on the respective computer—to see what 
they now look like. Some are ready to use. Other may 
require some changes in their format. 


Important There is no way, with InterFile or any other translation 
application, to transfer all of your Macintosh's 
features—fonts, for instance —to MS-DOS or ProDOS files. 
However, some of the missing features may be 
documented in the InterFile Log. (See "Keeping Track of 
Your Activity" in Chapter 8.) 


When you copy a Macintosh file to another file 
system, there are numerous characters, such as “å,” 
that cannot be represented. InterFile automatically 
chooses a similar character—in this case, “a.” 


The codes used to represent keyboard characters varv 
from language to language. The version of InterFile for 
each language—that is, English, French, German, and 
so on—contains language-specific translations of those 
codes. This means that you can't use the French 
version of InterFile to translate, from one operating 
system to another, files prepared in the English 
language. 
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InterFile Preliminary Notes 


Part 2: 
Conversion Routines for InterFile 


How to design and write your own 
conversion routines for InterFile, 
Version 1.0 


This section contains instructions and examples of conversion routines for InterFile, a program tor 
copying files between foreign file systems. During copying, a conversion routine is invoked to 
convert the data from one file system into a form palatable to the other file system. Conversion 
routines can be written independently of the InterFile application itself and linked in by the use ot 


resources. 


A note about terminology: If you are among those who have used earlier versions of 
InterFile, be aware that some of the terms used to describe InterFile features have changed. The 
terms check, uncheck, checked, unchecked, cvfChecked, Cvt_Chk, and CvtUnChk used to 
describe conversions have been replaced by activate, inactivate, active, inactive, cvfActive, Cvt_ 
Active and Cvt Inactive. In addition, the terms cvt Active and cvt_Inactive used in previous 
InterFile documents have been replaced by cvt_Appear and cvt_Disappear. 
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In this chapter you learn how to use some of 
InterFile’s more complex features, including: 


Oo How to let InterFile select the translators when 
you've selected the source files. 


n^ How to let InterFile select the source files when 
you've selected the translators. 


O Translating MS-DOS and ProDOS files that you've 
already copied onto a Macintosh disk. 


C Resolving filename conflicts. 

C Using the InterFile Log to keep track of your 
activity. 

D Setting the options for specific translators. 





IL MM 
Letting InterFile select the transiators 
When you're translating a large number of files created 


with a variety of applications, you might not want to 
take the time to figure out which translators to select. 


Don't worry. InterFile is designed to figure it out for 
you. Follow these steps. 
1. Select your source files and destination directory. 
See Chapter 7 for a step-by-step guide. 
2. Determine which menu you need fo use. 
It’s the menu that shows the source disk first. 
3. Select ail the translators in the menu. 


Do not, however, select two translators with the 
same source application. For example, don’t select 
“MacWrite to DCA” and “MacWrite to Wordstar" in 
the “Mac to MS-DOS” menu. If you do, InterFile uses 
only “MacWrite to DCA” because it appears first in 
the alphabetic list above the dotted line. 


Do not select Other Conversions unless you plan to 
add translators to the menu. (See “Translating Files 
That You've Already Copied,” later in this chapter.) 
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Part 2: interFile Conversion Routines 


The name of a conversion resource indicates what will appear in the menu of the appropriate 
conversions. If your routine converts MacWrite files to AppleWorks word processing files, then 
you would give it a resource type of "MCPD' and might name it "MacWirite to AppleWorks". If 
your conversion has a dialog box for options, its menu item should end with an ellipsis (...) to 
indicate that more interaction is needed. 


Conversions with ID numbers greater than 2000 are listed alphabetically at the top of a conversion 
menu. Conversions with ID numbers of 2000 or lower appear in the menu below those with ID 
numbers greater than 2000. The two groups of menu items are separated from each other by a 
dotted line, as shown in Figure 1. For ID numbers 2000 and below, the ID number of the 
conversion resource determines the order of the conversion routine in the menu: the higher the 
number, the higher up in the menu. There should always be a resource with ID number Q: this is 
the default conversion that takes place if none of the others do. Consider the group of resources in 
Table 1. These would produce the menus shown in Figure 1. (Note that any resource with ID = 0 
is always indicated by a diamond to the left of the corresponding menu item. The diamond 
indicates that the resource is always available and cannot be made inactive.) 


Resource Type ID # Name 

PDMC 7300 Applesoft to MS-Basic 
PDMC 2325 AppleWorks to Excel 
PDMC 15000 VisiCalc to SYLK 
PDMC 1200 TXT to MDS 

PDMC 1100 TXT to TEXT 

PDMC 0 Any File to Binary 
MCPD 2700 MacWirite to AppleWorks 
MCPD 3500 MultiPlan to VisiCalc 
MCPD 1000 TEXT to TXT 

MCPD 0 Any File to Binary 


Table 1. Sample conversion resources 


ProBos to Mac Mac to ProBDos 


Apptesoft to MS-Basic MacWrite to AppleWorks 
AppleWorks to Excel MultiPlan to VisiCalc 


Ui $ iCalc to SVLK m———Á'ÁDPP TEE 
TEXT to THT 


THT to MDS e Any File to Binary 

THT to TEHT Other Translations... 
e Any File to Binary 

Other Translations... 





Figure 1. Menus generated by Table 1 
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L—————M———MM———————————— 
Letting InterFile help select the source files 


At times, you may know which translator(s) you plan 
to select, but not know which files are eligible for 
that translation. For example, you may wish to convert 
all Wordstar files on your MS-DOS disk into MacWrite 
documents, but you don’t have the time to figure out 
which of your MS-DOS files were written with 
Wordstar. 

A file is eligible if it can be 


tronslated with a selected 
translator. 


Again, InterFile is designed to figure it out for you. 

Follow these steps to select eligible source files. 

1. Show the disk or folder containing possible source files in 
the InterFile control dialog box. 
See "Selecting Source Flles" in Chapter 7. 

2. Display the destination directory in the InterFile control 
dialog box. 
See "Selecting Destination Directories" in Chapter 7. 

5. Select the desired translator(s) in the appropriate InterFile 
menu. 
The appropriate menu is the one with the source 
operating system shown first. 

4. Choose Show Eligible Files from the File menu. 
The command is checked until you choose it again. 
In both directories InterFile dims the names of files 
that cannot be translated with the selected 
translator(s.) It also dims folders that do not contain 
eligible files at any level. 
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Part 2: InterFile Conversion Routines 


CONST maxdestnames = 15; 


TYPE  NameRec = RECORD 


nameCnt : integer; ( number of dest files | 
names : array(0..maxdestnames] of str255; { source/dest file names 
end; 


NamePtr - ^NameRec; 
NameHdl = ^NamePtr; | 


Figure 4. The NameRec record 


The NameCnt field contains the number of destination files. The Names array contains the name of 
the source file in Names[0], and the names of the destination files in Names[1] through whatever. 
The handle is originally large enough to contain one destination file name. 


The CvtTested flag in the conversion parameter block indicates whether the routine has been issued 
acvt Recognize command for this file. If CvtTested is TRUE, then the routine needn't check the 
file for whatever it uses as recognition criteria—the CvtAccepted flag will indicate whether the file 
was accepted or not. However, if CvtTested is FALSE, then the conversion routine should once 
again check the file for recognition during any of the following commands: cvt. Recognize, cvt_ 
NewName, and cvt File. 


Conversion routines 


You can give your conversion routine any name you like. Here's how you would declare one in 
Pascal with the name MyConvert: 


Function MyConvert (Message : integer; VAR ConvertData : longint; 
Param : longint; Self : handle) : longint: 


The first parameter, Message, identifies the desired operation. It has one of the following values: 


CONST cvt Init = 0; { do any conversion routine initialization } 
cvt Finis -1; { do any clean up and disposal } 
cvt Get = 2; | Return current status ) 
cvt Set = 33; { Set current status } 
cvt Active = 4; { Item is active, that is, checked in menu } 
cvt Inactive =5; { Item is inactive, that is, unchecked in menu ; 
cvt NewName = 6; | If recognized, return new name for selected file 
cvt File = 7; { If recognized, convert the selected file } 
cvt Recognize = 8; { Return NoErr if selected file is recognized } 
cvt Appear = 9; { This routine is now listed in a menu } 
cvt Disappear = 10; { This routine is no longer listed in a menu } 
cvt Load = 11; { Pre-load any resources you might need } 
cvt About = 12; [ Provide "About this conversion" information } 
cvt GetDefault = 13; { Get default information about the conversion j| 
cvt SetDefault = 14; { Set default information for the conversion ) 
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1. Select the source files and destinattion directory in the 
InterFile control dialog box. 
Since both the source files and destination disks are 
Macintosh disks, the “Mac to Mac" menu appears. 
See "Selecting Source Files" and "Selecting 
Destination Directories" in Chapter 7. 

2. Select Other Conversions in the "Mac to Mac" menu. 


A dialog box appears, listing translators from each 
of the other possible InterFile menus. 


ART 8-3 


Figure 8-3 
A typical Other Conversions dialog box 


5. Select the translators you wish to add to the "Mac to 
Mac" menu and click Done. 
The next time you use the Mac to Mac menu, the 
translators you selected appear. They remain in the 
menu until you quit InterFile. 
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The following constants are defined for the status: 


CONST cvfActive = $0001; { item is active, that is, checked in the 

menu } 

cvfGray = $0002; ( item is grayed-out } 

cvfBold = $0010; ( item is bold ] 

cvfItalic = $0020; { item is italicized } 

cvfUnderline = $0040; { item is underlined } 

cvfOutline = $0080; { item is outlined } 

cvf Shadow = $0100; { item is shadowed } 

cvfAbout = $0200; { About information is available for the 
item } 

cvfUserl = $1000; { user bit 1 } 

cvfUser2 - $2000; ( user bit 2 ] 

cvfUser3 = $4000; ( user bit 3 } 

cvfInited = $8000; ( conversion routine is initialized } 


The Set Status routine 


The message Cvt. Set is sent when InterFile wants to set the status to the value contained in Param. 
[t is currently used only with conversion routines with resource ID = 0 (to force the Active bit on) 
and after an unsuccessful Cvt, Appear message (to force the Active bit off and the Gray bit on). 


The Activate routine 


The message Cvt. Activate is sent when the user selects an inactive conversion from the conversion 
menu. The conversion routine must update its status and return it in the function result. The 
conversion routine is not forced to set the Active bit in the status in response to this message—for 
example, if your routine displays a dialog for the user to choose certain options and if the user 
selects Cancel, the Active bit must not be set. 


The Cvt_ Activate message is also sent if the user holds down the Option key while selecting a 
menu item that can be activated. The message is sent whether or not the item is active. When there 
is a dialog box for an item, holding down the Option key allows the user to open the dialog box and 
check the current options for the item. 


The Cvt_Activate message is sent always for menu items with resource ID = 0 (no Cvt_Inactivate 
message is ever sent). 


Note: InterFile looks at only the Active bit in the function result after sending Cvt_Activate—it 
assumes that the only time the other appearance bits of the menu item will change is after the Cvt 
Appear message is sent. However, a full status must be returned from Cvt. Activate, in case 
InterFile changes in the future and allows dynamic appearance. 
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o A destination file has the same name as an existing 
folder (or a destination folder has the same name a5 
an existing file) in the destination directory. 


An alert box allows you to click the Rename button 
to display a window in which you can create a new 
name for the destination file or folder. You can also 
click Cancel. 


4 Two destination filenames or folder names are the 
same. This can happen if you are converting 
Macintosh files to MS-DOS or ProDOS. Because 
those file systems do not allow filenames as long as 
those allowed on the Macintosh, sometimes the 
Macintosh filenames are truncated, turning similar 
filenames into duplicate names. 


An alert box allows you to click the Rename button 
to display a window in which you can create a new 
name for the destination file or folder. You can also 
click Cancel. 


D e amaaaaaaaIuaaaaasaasasaeaaauasasasauaiuluasasaaasosaaeeaaoelaaMMMll 


To change names 


When you need to rename a file, click Rename in 
whichever alert box InterFile presents. The Rename 
window appears (See Figure 8-5). 


*% Note: If you anticipate conflicts, or want to change 
filenames for any other reason, you also can 
activate the Rename window before clicking 
Translate. Choosing Rename Destination Files from 
the File menu. 


Source file and folder name 

cons identifying type of source file 
Symbols identifying filename conflicts 
Destination filenames 

Scroll bar for both sides of list 

Lagend for filename conflict symbols 


Button to confirm changes and close window 
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Part2: InterFile Conversion Routines 


The Disappear routine 


The message Cvt_Disappear is sent whenever the menu that the conversion routine was displayed 
in disappears from the user's menu bar. The conversion routine may want to dispose of any extra 
memory it allocated during conversion or when it became active. 


The Recognize routine 


The message Cvt_Recognize is sent to find out if a particular file can be handled by a particular 
conversion routine; the conversion routine must return Accept (= 0) if the file is recognized, and 
Unaccept (= 1) if not. Only routines whose Active bits are set in the status receive this message. 
When looking for a conversion routine for a particular file, InterFile queries all conversion routines 
of the appropriate resource type in the order they appear in the menu; as soon as a conversion 
routine recognizes the file, the query is stopped. 


A pointer to the conversion parameter block is passed in Param with the following values: 


cvtLogProc Pointer to the log procedure 

cvtStatProc Pointer to an empty procedure (simply returns) 

cvtFrID Resource ID of FS for the file 

cvtFrData Pointer to FS global data 

cvtFrVRef Volume reference of disk file it is on 

cvtFrPar Parent ID of directory file it is in 

cvtNames^^.names[O] Name of file 

cvtTested TRUE if you've already checked this file for recognition 
cvtAccepted If CvtTested is TRUE, this indicates whether file was accepted 


All other fields in the parameter block have undefined values. 


The conversion routine can use whatever criteria it wishes to decide if it recognizes the given file, 
including opening the file and reading its contents. The investigation into recognizing a file should 
be as efficient as possible—don't bother doing a trial conversion of the entire file; that will come 
later. It's possible that the routine guesses wrong and later on will not be able to convert the file. 
This is regretable but not completely disastrous; see the end of "The Convert File Routine" section. 
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InterFile Preliminary Notes 


4 Note: If you opened the Rename window from the 
File menu, click the OK button that is shown in 
place of the Translate button. Unless you quit 
InterFile, it uses the changed names the next time 
you translate files. 


—— MM —————M—M—M————M————— 
Keeping track of your activity 


Whenever you copy or remove a file, InterFile adds 

listings to the end of the InterFile Log. The InterFile 

Log shows the following information: 

o the time and date translation Cor deletion) begins 
and ends 

o the menu used for translation 

o the source and destination name of each file and 
folder. Source files (or folders) within folders are 
indented. 


^ the translation used for each item 
O error messages 


0 information about a conversion specified in the 
translator file. For example, the entries for a 
translation from MacWrite may show fonts and 
character styles that couldn't be carried over into 
MS-DOS or ProDOS files. 
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Figure 8-6 
Sample entries in the InterFile Log 
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The Convert File routine 


The message Cvt. File is sent when it is finally time to actually copy a file from one disk to another: 
the conversion routine must return Accept (= 0) if the file is recognized, and Unaccept (= 1) if not. 
You must use the same algorithm as was used by the Recognize routine to determine if you accept 
the file. For efficiency, InterFile will let you know if you've already been asked about this file (in 
the cvtTested field of the parameter block) and, if so, what your response was (in the cvtAccepted 
field of the parameter block). 


Only routines whose Active bits are set in the status receive this message. When looking for a 
conversion routine to copy a particular file, InterFile queries conversion routines of the appropriate 
resource type in the order they appear in the menu. If more than one conversion accepts the file, 
the user is asked which one should perform the conversion. 


A pointer to the conversion parameter block is passed in Param with the following values: 


cvtLogProc Pointer to the log procedure 
cvtStatProc Pointer to the status procedure 
cvtFriD Resource ID of source FS 

cvtToID Resource ID of destination FS 
cvtFrData Pointer to source FS global data 
cvtToData Pointer to destination FS global data 
cvtFrVRef Volume reference of source disk 
cvtToVRef Volume reference of destination disk 
cvtFrPar Parent ID of source file 

cvtToPar Parent ID of destination file 


cviNames^^.namecnt Set to the number of destination files 

cvtNames^^.names[0] Name of source file 

cvtNames^^.names[1...] Names of destination files 

cvtTested TRUE if you've already checked this file for recognition 
cvtAccepted If CvtTested is TRUE, this indicates whether file was accepted 


If the conversion routine recognizes the file, it can then do anything it wishes to copy it over to the 
destination disk. The conversion routine must call the status procedure periodically with the 
appropriate status string and percentage-complete value so that the user can tell how things are 
going and potentially cancel the operation. 


If the status procedure returns FALSE, then the user has cancelled the copy operation. The 
conversion routine must close and delete any files it has created, and return CvtCancel (7 2) as the 
function result. 


If an error occurs when converting the file, you should log the error in the user log, but still accept 
the file. If the conversion routine determines that it can convert the file (that is, it plans on returning 
Accept), but later runs into a disk error, it should still return Accept as the function result. Chances 
are, if you get a disk error, so will any other conversions, so you should accept the fact that you 
did all you could, log the error in the user log, and tell InterFile that conversion of the file 1s 
finished. 
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Figure 8-8 

The “MS-DOS to Mac" Text translator options dialog box 
To change settings, follow these steps. 

1. Click the appropriate buttons or check boxes. 

2. Type in numbers where necessary. 

5. Click OK to confirm and close the options dialog box. 
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Importing conversions 


InterFile allows the user to "import" conversions from one menu to another through the Other 
Translations option at the bottom of each conversion menu. If a conversion is imported, InterFile 
considers each of the occurrences of the conversion as separate entities (they just happen to use the 
same resource) and will keep track of separate data pointers for them. Therefore, at the time when 
a conversion is imported to a new menu, that conversion will receive the following messages in 
succession: cvt Init, cvt. Appear, and cvt, Active. The cvt. Active message is sent to force the 
menu item to be checked in the new menu (and possibly to display a dialog box for options). 


Because there may be more than one instance of your conversion in various menus, it is important 
that you use the data-pointer mechanism provided; do not attempt to store data in locations residing 
in your own code (for instance, in-line data in an assembly language program). This 1s a bad 
practice anyway, since your resource may be purged and when it is later read back in, any data 
previously stored in your code would be lost. 


InterFile will not allow a user to import a conversion to its own "mirror menu"; that is, if your 
conversion is of type PDMC; it will never be imported to a menu whose type is ‘MCPD.’ It 
might get imported to a menu of type 'MCMC' or PDPD,' or even (in a pathological case) 
'MSMS.' Your conversion routines would be justified in not running on some weird configuration 
(but please tell the user that when it happens). 


How files get converted 

[t is useful to understand the sequence in which messages are sent to conversions. The most 
important messages are, of course, related to the actual conversion of the file, but the other 
messages have their own utility as well. 


The following sequence illustrates a simple conversion. 


User Message sent to conversion 
* Start InterFile cvt. Init—initialize conversion for all menus 
e Insert Disk cvt_Appear—menu in which conversion resides 
appears in the menu bar 
cvt. Get—get the menu's appearance 
e Select Files nothing 
* Press Copy cvt. NewName— get the name of the destination file 


cvt. File—convert the file 


¢ Exit InterFile cvt_Finis 
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About InterFile and conversion routines 


InterFile is a tool which allows the user to transfer files and directories from one disk to another. 
even if the disks belong to different file systems. When a file is copied from one file system to 
another, it is often useful to convert the form of the data from one representation to another. One 
simple example is a text file in EBCDIC which needs to be converted to ASCII—conversion takes 
place on a byte-by-byte basis. Another more complicated example would be a VisiCalc® 
spreadsheet on an Apple II being converted to an Excel& document on the Macintosh. 


InterFile was designed with the idea that many different conversion routines could be written as the 
various needs for file conversion crop up. These routines reside as special resources either in the 
InterFile application itself, or in special auxiliary files known as translator files. A conversion 
routine can be developed independently of the source for InterFile itself and then included in a 
translator file that resides in the same folder as the application. When InterFile starts up, it will 
automatically display the appropriate menu items, and so forth, for that conversion routine. 


Audience 


InterFile conversion routines can be written by anyone with access to a development system for the 
Macintosh. The routine can be written in Pascal, assembly language, or any other suitable 
language; the only requirement is that its entry point must be at the beginning. Routines should 
also include a header. The form of a conversion routine header is described in the section 
"Conversion Routines" later in this part. This section describes the routines in terms of Pascal, and 
some aspects inherent in Pascal (particularly strings) need to be taken into account when using 
other languages. 


Conversion resources 


Conversion resources reside either in the InterFile application itself or in auxiliary files called 
translator files. The translator files have a file type of 'VISA' and a creator of PSPT. When 
InterFile starts up, it looks in its own folder for any existing translator files and opens them up 
using OpenResFile. The number of translator files that InterFile can open is restricted only by the 
Macintosh operating system, and not by InterFile itself. 


Conversion resources have a type based upon what they convert from and to. The resource type IS 
built up out of the two-letter nickname that each file system has. Below are some nicknames of 
present file systems supported by InterFile: 


Nickname Fil m 

MC Macintosh MFS and HFS 
PD ProDOS 

MS MS-DOS 


Therefore, a conversion routine that copies from Macintosh to ProDOS would have a resource tvpe 
of 'MCPD'; from ProDOS to Macintosh, PDMC.' 
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Version 1: 
User Message sent to conversion 
* Click Copy cvt_NewName—get the name of the destination file. 


Conversion À says it recognizes the file and 
returns a new narne for it. 

cvt_File—convert the file. Conversion A discovers it 
really can't convert this file, because of a disk 
error. Chances are nobody else can convert it 
either, so conversion À still returns Accept after 
logging the disk error in the user log. 


Version 2: 


User Message sent to conversion 


e Click Copy cvt_NewName—get the name of the destination file. 
Conversion À says it recognizes the file and 
returns a new name for it. 

cvt. File—convert the file. Conversion A discovers it 
really can't convert this file because it is not the 
correct kind of file. It's possible someone else can 
convert it, so we give them a chance by returning 
Unaccept. 

cvt_File—convert the file. Conversion B now receives 
the cvt. File message with cvtTested equal to 
False. B can convert the file, so it logs the fact 
that it is now taking over the conversion, and 
completes the conversion of the file. 


Calling the file systems 


The file systems that are used by InterFile are stored in resources in a similar manner to conversion 
routines. Therefore, to make calls to them it is necessary to get a handle to their location in memory 
(their current location—except when actually running, they are purgeable and relocatable). The 
conversion parameter block contains the resource ID for the two file systems that a conversion 
routine will be concerned with. The resource type of a foreign file system is '4NFS.' Any global 
storage that a file system uses is allocated in a manner similar to the global storage allocated for 
conversion resources. Therefore, it is necessary to send along a pointer to that global storage every 
time the file system is called. The conversion parameter block contains the pointer to this storage. 


All foreign file systems designed for InterFile try to look like the Macintosh file system as much is 
possible. The conversion parameter block contains the volume reference numbers, parent ID 
numbers, and file names for both source and destination files. This information should be 
sufficient for identifying, creating, opening, modifying, and even deleting files. Each file system 
provided for InterFile must have a document discussing just where and how it differs from the 
Macintosh file system. If one of the file systems you work with is the Macintosh file system itself 
(that is, you are using a conversion routine from the Macintosh to a foreign disk, or vice versa), 
then you need to go through the InterFile foreign file system interface to maintain integrity and 
robustness. 
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Conversion resources must have ID numbers that are multiples of 25 and range from 1000 to 
25000 (except for the default resource with ID = 0). Ifa conversion routine with ID = xxx0O uses 
other resources, those resources must have ID numbers between xxx00 and xxx24 (and similarly 
for other multiples of 25). This does not guarantee that there will be no conflict, of course, but it 
allows a developer to inspect a translator file with a utility such as ResEdit and fairly easily detect à 
safe region for a new conversion routine. Or, if transferring resources into another file (say, 
InterFile itself), it allows a fairly easy way to detect potential conflicts and resolve them. No 
guarantees, just possibilities. 


Conversion menus 


When the user selects disks in both windows of the InterFile control panel, one or two menus will 
appear in the menu bar after the Control menu. If the disks are from the same file system, only one 
menu will appear; different file systems will cause two menus to appear. In the menus are the 
names of the available conversion routines in the order described above. 


Users select which of these conversion routines they wish to be active by checking them. Each 
conversion resource supports a control call that sets or clears the check mark for the menu item, and 
a status call which returns the current setting of the check mark for the item. In this way, a 
conversion resource may force itself to be always active (or always inactive), or provide a default 
setting if the resource has some preference as to how the corresponding menu item is to be checked 
upon startup. To the left of the last item in a menu (with resource ID = 0) there 1s always a 


diamond. 


When the user presses the button marked Translate in the middle of the control panel, the menu title 
above the appropriate menu is highlighted. In order to decide which resource will actually move 
the file, InterFile will call a recognition routine in each active resource. These recognition routines 
are called in the order the resources appear in the menu, beginning at the top of the menu. A 
recognition routine returns Unaccept if it can't handle the given file (because of its type, name, or 
extension, or whatever else it uses as criteria) and Accept if it does. Resources with ID = 0 should 
always return Accept. If more than one routine (other than the default routine) recognizes the file, 


then InterFile asks the user which of the translations to use. 


The last menu item in each conversion menu is Other Translations. When this item is selected, a 
dialog box appears that allows users to add additional conversions to the menu. This feature allows 
conversions of files that do not need to be taken from one file system to another. For example, 
suppose a user has used a telecommunications program to move an exact Copy of an MS-DOS file 
onto a Macintosh disk. To convert the file to a Macintosh file, an MS-DOS to Macintosh item 
needs to be added to the Mac to Mac menu. When writing a new conversion routine, keep in mind 
that your routine must allow for conversions within the same file system. In other words, the 
routine must be robust enough to deal with files on any kind of disk; don't assume that a file will be 
stored on only one file system. 
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The async parameter has the same meaning as in the Macintosh world: the requested operation will 
be executed asynchronously if supported. However, be aware that it is unlikely that foreign file 
systems will support full asynchronous operation in their InterFile versions. 


The final parameter, FSRoutine, contains a handle to the resource that contains the foreign file 
system. You must obtain this handle by performing a GetResource call using the resource ID 
provided in the conversion parameter block. 


Skeleton conversion routine 


On the following pages you will find a skeleton conversion routine, as well as listings 
for: 


« aroutne header 
* aresource definition file 


¢ an MPW shell script for assembling, compiling, and linking the parts of a conversion 
routine 
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---Copy ing Begun--- 
AW --> AW (Folder) 
A Spreadsheet --> A Spreadsheet (Straight Copy) 
APPLEWORKS. --» APPLEWORKS. (Straight Copy) 
November News --? November News (Straight Copy) 
PICTURE --» PICTURE (Straight Copy) 
SEG.00 --» SEG.OO (Straight Copy) 
SEG.MO --» SEG.MO (Straight Copy) 
SEG.M1 --» SEG.M1 (Straight Copy) 
SEG.PR --» SEG.PR (Straight Copy) 
SEG.XM --> SEG.XM (Straight Copy) 
November News --> November News (Straight Copy) 
STARTUP --» STARTUP (Straight Copy) 
SUS.OBJ --» SUZ.OBJ (Straight Copy) 
USER.PROFILE --» USER.PROFILE (Straight Copy) 


Figure 3. Indentation in the user log 


The CvtStatProc field is also a pointer to a procedure (actually a function) that informs the user of 
the current status of the conversion. The form of the function is 


Function CallStat(statMsg : str255; statpct : integer; 
destfnum : integer; statproc : procptr) : boolean; 


The StatMsg parameter contains a Pascal string that will be displayed on the status display during 
conversion. The StatPct parameter is an integer from 0 to 100 that indicates how far along the 
conversion is. The DestFNum parameter indicates which destination file (if there is more than one) 
the conversion routine is currently dealing with. The last parameter, StatProc, must be given the 
value of the CvtStatProc field. 


The CvtFrID and the CvtToID fields in the conversion parameter block contain the resource ID 
numbers of the source and destination file systems, respectively. More information on how to call 
routines in the various file systems is given in the section "Calling the File Systems" later in this 
part. 


The CvtFrData and the CvtToData fields contain pointers to global data needed by the source and 
destination file systems, respectively. 


The CvtFrVRef and the CvtToVRef fields contain the volume reference numbers of the source and 
destination volumes, respectively. 


The CvtFrPar and the CvtToPar fields contain the ID numbers of the source and destination 
directories, respectively. 


The CvtNames field contains a handle to the names of the source and destination files, as shown in 
Figure 4. 
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InterFile Preliminary Notes 


Part 3: 
Using ProDOS From InterFile Conversion 


Routines 


How to use the ProDOS routines 
provided with InterFile, Version 1.0 


This part contains information on the implementation of the ProDOS routines that come with 
InterFile. 


Before reading this part, you should have some familiarity with InterFile, be familiar with its 
operation as described in Part 1, and have read the Part 2 of the Preliminary Notes, "Conversion 
Routines for InterFile.” You should also be familiar with /nside Macintosh, in particular "The 
Resource Manager" chapter in Volume I and "The File Manager" chapter in Volume IV. 


About InterFile and ProDOS 


InterFile is a tool which allows a user to transfer files and directories from one disk to another, 
even if the disks belong to different file systems. When a file is copied from one file system to 
another, a conversion routine changes the form of the data from one representation to another. This 
conversion routine has full control over the process of reading the source file and writing the 
destination file; it makes calls to the different file systems through a common interface described in 
Part 2 of the Preliminary Notes, "Conversion Routines for InterFile." 


ProDOS is the Professional Disk Operating System for the Apple II line of products. The data 
structures used by ProDOS on its disks allow for a hierarchical, tree-structured file system similar 
to the Macintosh hierarchical file system (HFS). However, there are significant differences in the 
overall philosophy of file management (besides the obvious differences in file storage) between 
ProDOS and HFS. 
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The Get Status routine 


The message Cvt Get is sent when InterFile wants the current status of the conversion routine, 
which is returned as the function result. This message is sent after every Cvt. Active message. The- 
status of the conversion routine is stored as a 32-bit quantity, as shown in Figure 5. 


16 15 14 98765423210 


Lee Lc Ese E EETTTTTTT 


inited About 
Shadow 
Outline 
Underline 
Italic 
Bold 
Reserved: Must be 0 
Reserved: Must be O 
Gray 
Checked 


Figure 5. Conversion routine status 


The Active bit indicates that the menu item corresponding to this conversion routine is currently 
checked. The Gray bit indicates that the menu item is disabled (grayed-out). In this case, the user 
has no way to change whether the menu item is active or not. 


Bits 2 and 3 are reserved for future use. Always keep them set to zero. 
The Bold, Italic, Underline, Outline, and Shadow bits all refer to style settings for the menu item. 


The About bit is set when "About" information is available for a conversion routine. This bit 
controls whether an About ... button for the routine appears in the About dialog box. 


Bits 10 and 11 are reserved for future use. Always keep them set to zero. Bits 12, 13, and 14 will 
never be used in the future, and can be used by the conversion routine for whatever it wants. 


The Inited bit should be always set (if the initialization fails, InterFile clears this bit in its own copy 
of the conversion routine's status, and never calls the routine again). 


Bits 16 through 31 may be used in future versions of InterFile, but they are not used in version 
1.0. You can use these bits if necessary, but be aware that this may not be true for later versions. 
To assure complete compatiblity with future releases, set these bits to zero. 
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ProDOS calls from InterFile 


The following list shows the behavior of the various file system calls when issued through the 
ProDOS foreign file system. 


FFGetVInfo 
io VolIndex 
If greater than zero, retums an error. 
If equal to zero, returns information about file specified by ioVRefNum. 
If less than zero, uses ioNamePtr and ioVRefNum in the standard way. 


The following fields return zeros: 
icAllocPtr 
iO VNxtCNID 
ioVFSID 
ioVSeqNum 
ioVWrCnt 
ioVFndrInfo 


The following fields return information: 
ioNamePtr - if ioVRefNum used to specify volume, returns name of volume specified 
ioVRefNum - if ioNamePtr or drive number used to specify volume, returns reference 
number of volume 
ioVCrDate - volume creation date 
ioVLsMod - same as creation, or creation date + 1 if ProDOS access bit 
indicates volume has been changed 
ioV Aub - volume attributes (reflects access bits in ProDOS) 
$8000 - if locked by software ($02 access bit clear) 
$0800 - if may not be read ($01 access bit clear) 
$0400 - if may not be renamed ($40 access bit clear) 
$0200 - if may not be reformatted ($80 access bit clear) 
$0080 - if locked by hardware (write protected disk) 
$0040 - if any file is open 
all other bits cleared 
NOTE: The Macintosh does not support recognition of bits $0800, 
$0400, and $0200 as described above—they are included to 
reflect the access bits in the ProDOS directory entry more 
accurately. 
ioVNmFls - number of files in root directory 
i0 V BitMap - first block of volume bit map 
ioVNmAIBlks - number of allocation blocks 
ioV AIBlkSiz - 512 
ioVClpSiz - 512 
ioAIBISt - first block in volume block map 
iOVFrBlk - number of unused allocation blocks 
ioVSigWord - PD' 
ioVDrvinfo - drive number 
ioV DRefNum - driver reference number 
io V BkUp - same as creation date 
ioVFilCnt - number of files on volume 
ioVDirCnt - number of directories on volume 
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The Inactivate routine 


The message Cvt_Inactivate is sent when the user selects an active conversion from a conversion 
menu and the Option key is not held down. (For the details of what happens when the user selects 
a conversion with the Option key held down, see the description of the Active routine.) The 
conversion routine must update its status and return it in the function result. The conversion 
routine is not forced to clear the Active bit in the status in response to this message—for example. it 
may be that the routine always wants to be active. 


Note: InterFile looks at only the Active bit in the function result after sending Cvt Inactivate—it 
assumes that the only time the other appearance bits of the menu item will change is after the Cvt_ 
Appear message is sent. However, a full status must be returned from Cvt Inactivate, in case 
InterFile changes in the future and allows dynamic appearance. 


The Appear routine 


The message Cvt, Appear is sent whenever the conversion routine appears in an active menu with a 
new pair of disks. A pointer to the conversion parameter block is passed in Param with the 
following values: 


cvtLogProc Pointer to the log procedure 

cvtStatProc Pointer to an empty procedure (simply returns) 
cvtFrID Resource ID of source FS 

cvtToID Resource ID of destination FS 

cvtFrData Pointer to source FS global data 

cvtToData Pointer to destination FS global data 
cvtFrVRef Volume reference of source disk 

cvtToVRef Volume reference of destination disk 


All other fields in the parameter block have undefined values. 


Upon receiving this message, the conversion routine can get information about the volumes 
involved and decide if the appearance of its menu item should change (InterFile sends a Cvt_Get 
message before displaying the menu to determine how the appearance may have changed). As 
discussed before, the conversion routine may also wish to allocate more global memory upon being 
activated. 


Be aware that it is possible for the same disk to appear in the left and right sides of the InterFile 
control window. You can check for this condition by seeing if cvtFrID and cvtToID match and 
cvtFrVRef and cvtToVRef match. 


The conversion routine must return 0 if activation was successful, or an error code (usually some 
memory allocation error, or a file system error) if unsuccessful. If unsuccessful, InterFile sends 
the message Cvt_Set to set the menu item's status to unchecked and grayed-out. 


Note: Not all Cvt. Appear messages have a matching Cvt Disappear message sent. It is possible 
to get two or more Cvt Appear messages in a row, if the user presses the Drive button on a 
window and the new disk is from the same file system as the former disk. In this case, no Cvt_ 
Disappear message is sent, because the menu never really disappeared, and a Cvt. Appear message 
is sent, because a new source or destination disk is involved. You may also get a Cvt. Appear 
message if an item is imported from one menu to another. Whether the item is checked after it is 
imported depends on the defaults for the item. 
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FFGetFInfo 
The following fields return zero: 
ioFIFndrInfo 
fdLocation 
fdFldr 
ioFIStBlk 
ioFIRStBlk 


The following fields return values: 
ioNamePu-—if file specified by ioFDirIndex 
ioFRefNumber - file reference number if the file is open 
ioFlAttrib - file attributes - reflects some of ProDOS access bits 
$01 - if file locked ($02 access bit clear) 
$02 - if file may not be deleted ($40 access bit clear) 
$04 - if resource fork is open (MacUnary files only) 
$08 - if data fork is open 
$20 - if file may not be renamed ($80 access bit clear) 
$40 - if file is in MacUnary format 
$80 - if either fork is open 
all other bits clear 
NOTE: The Macintosh does not support recognition of bits $02 and $20 
as described above—they are included to reflect the access 
bits in the ProDOS directory entry more accurately. 
ioFiFndrInfo 
fdtype - reflects ProDOS file type and auxiliary file type 
TEXT - TXT ($04) with zero aux file type 
'BINA' - typeless ($00) with zero aux file type 
"ZSYS' - SYS with $2000 aux file type 
Otherwise: 
4 bytes: 
P'- Ascii $70 
file type - one byte value, ProDOS file type 
aux file type - two byte value, ProDOS auxiliary file type 
fdcreator - 'pdos 
fdFlags - reflects the "Read-allowed" access bit 
$4000 - if file is invisible ($01 access bit) 
all other bits clear 
ioDirID - file number 
ioFILgLen - data fork logical length 
ioFIPyLen - data fork physical length 
ioFIRLgLen - resource fork logical length (if MacUnary format) 
ioFIRPyLen - resource fork physical length (if MacUnary forrnat) 
ioFICrDat - creation date 
ioFIMdDat - modification date 
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The NewName routine e 


Many times, two file systems have different rules and conventions for naming files. When copying 
to a new file on the destination file system, InterFile gives a conversion routine a chance to suggest. - 
a name that would fit on that file system. Any names the routine suggests must be acceptable to the 
destination file system. You can check this through the FFOKFName call. 


To come up with a new name, a conversion routine should not interrupt the user to ask for a new 
name. If you don't want to go to the trouble of thinking up new names, you can ask the file system 
to provide a new name through the FFMakeFName call. 


The message Cvt NewName is sent to get a suggested new name for the converted version of a 
particular file; the conversion routine must return Accept (= 0) if the file is recognized, and 
Unaccept (2 1) if not. You must use the same algorithm as was used by the Recognize routine to 
determine if you accept the file. For efficiency, InterFile will let you know if you've already been 
asked about this file (in the cvtTested field of the parameter block) and, if so, what your response 
was (in the cvtAccepted field of the parameter block). 


Only routines whose Active bits are set in the status receive this message. When looking for a new 
name for a particular file, InterFile queries conversion routines of the appropriate resource type in 
the order they appear in the menu. If more than one conversion accepts the file, the one that 
appears nearest the top of the menu gets the honor of suggesting a name. 


A pointer to the conversion parameter block is passed in Param with the following values: 


cvtLogProc Pointer to the log procedure 

cvtStatProc Pointer to an empty procedure (simply returns) 

cvtFrID Resource ID of source FS 

cvtToID Resource ID of destination FS 

cvtFrData Pointer to source FS global data i 
cvtToData Pointer to destination FS global data 

cvtFrVRef Volume reference of source disk 

cvtToVRef Volume reference of destination disk 

cvtFrPar Parent ID of source file 

cvtToPar Parent ID of destination file 


cvtNames^^.namecnt Set to 1, assuming one destination file 

cvtNames^^.names[0] Name of source file 

cvtTested TRUE if you've already checked this file for recognition 
cvtAccepted If CvtTested is TRUE, this indicates whether file was accepted 


All other fields in the parameter block have undefined values. 


The conversion routine must place the new suggested name in the conversion parameter block in 
the field CvtNames^^.names[1]. If more than one destination file is to be created, then the name 
count in the CvtNames record must be changed, and additional names added. You must always 
check if the size of the CvtNames handle is large enough to handle additional names, and if not, 
change the size of the handle. 


Note: Even though the conversion routine is asked to provide new names for the destination files. 


remember that the user has final say on destination file names. Users may want to change your 
suggested names to suit their needs, or to avoid conflicts with existing files. 
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FFGetCatinfo 
The following fields return zero for files: 
ioFIFndrInfo 
fdLocation 
fdFldr 
ioFIStBlk 
iOFIRStBlk 
ioFIXFndrInfo 


The following fields return values for files: 
ioNamePr - if file specified by ioFDirIndex 
ioFRefNumber - file reference number, if the file is open 
ioFlAttrib - file attributes - reflects some of ProDOS access bits 
$01 - if file locked ($02 access bit clear) 
$02 - if file may not be deleted ($40 access bit clear) 
$04 - if resource fork is open (MacUnary files only) 
$08 - if data fork is open 
$20 - if file may not be renamed ($80 access bit clear) 
$40 - if file is in MacUnary format 
$80 - if either fork is open 
all other bits clear 
NOTE: The Macintosh does not support recognition of bits $02, $20 
and $40 as described above—they are included to reflect 
the access bits in the ProDOS directory entry more accurately. 
ioFIFndrInfo 
fdtype - reflects ProDOS file type and auxiliary file type 
TEXT’ - TXT ($04) with zero aux file type 
‘BINA’ - typeless ($00) with zero aux file type 
"ZSYS' - SYS with $2000 aux file type 
Otherwise: 
4 bytes: 
'p' - Ascii $70 
file type - one byte value, ProDOS file type 
aux file type - two byte value, ProDOS auxiliary file type 
fdcreator - ‘pdos’ 
fdFlags - reflects the "Read-allowed" access bit 
$4000 - if file is invisible ($01 access bit) 
all other bits clear 
ioDirID - file number 
ioFILgLen - data fork logical length 
ioFIPyLen - data fork physical length 
ioFIRLgLen - resource fork logical length (if MacUnary format) 
ioFIRPyLen - resource fork physical length (if MacUnary format) 
ioFICrDat - creation date 
ioFIMdDat - modification date 
ioFIBkDat - backup date, same as creation date if Changed access bit 
is set, same as modification date otherwise 
ioFIParID - ID of parent of specified file (2 indicates root) 
ioFlCipSiz - 512 
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[f the conversion routine determines that it can convert the file (that is, it plans on returning 
Accept), but later on finds out it can't do the job, then it has two options: 1) if the CvtTested and 
CvtAccepted fields of the parameter block are TRUE, then the routine should log its apologies to 
the user log and return Unaccept to allow another conversion to take over, or 2) if the CvtTested 
field is FALSE, then just retum Unaccept. The latter option will only occur when another 
conversion in front of you has failed to convert the file as expected. Usually the CvtTested and 
CvtAccepted fields are set to TRUE because you were asked to provide a new name earlier in the 
process. | 


The Load routine 


When users have only a two-disk system, they may wish to eject the disk that contains InterFile. 
Before the disk is ejected, all conversion routines receive the cvt. Load command to allow them to 
load any resources they need. It is possible that future activity could cause these resources to be 
purged, but with luck, they will still be in memory when they are needed and the user won't have 
to do a "floppy shuffle" in the middle of copying a file. 


The About routine 


When the user looks at the About InterFile item in the Apple menu, there appears a list of all the 
conversion routines available. The user can select any of the routines and InterFile will display a 
little information about that routine. The cvt. About command helps serve this purpose. If the 
conversion routine returns 0 as the function result, InterFile assumes that the conversion routine 
took care of displaying the About information. If the function result is nonzero, then InterFile uses 
that value as the resource ID of a resource whose type is 'TEXT and that contains only printable 
ASCII characters and carriage returns. The text will be displayed as is in a TextEdit window with 
one exception: tab characters are converted to 4 spaces. 


The Get Default routine 


InterFile allows the user to create InterFile documents. These documents contain default settings 
that take affect when the user launches InterFile. When InterFile sends a cvt GetDefault command. 
it is requesting a handle to data that can be stored in an InterFile document. Use the NewHandle 
routine to create a handle of the correct size, fill it with data, and return it as the function result. 
InterFile will dispose of the handle; do not dispose of it in your routine. 


The Set Default routine 


InterFile allows the user to create InterFile documents. These documents contain default settings 
that take affect when the user launches InterFile. When InterFile sends a cvt_SetDefault command. 
it is passing a handle to data that can be stored in an InterFile document. InterFile will dispose ot 
the handle; do not dispose of it in your routine. 
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ioFDirindex = -1 
INPUT 
ioNamePtr - ignored 
ioDirID - if 0, use ioVRefNum for volume and directory, else use ioDirID for directory 
OUTPUT 
ioNamePtr^ - returns name of directory specified by ioVRefNum and ioDirID 
ioDirID - returns number of directory (ioDrDirID) specified by ioVRefNum and ioDirID 
ioFIParID - returns directory number of parent of directory in question 


FSetCatInfo 
The following fields are ignored for files: 
ioFlFndrInfo 
fdLocation 
fdFldr 
ioFIXFndrinfo 
ioFlClpSiz 


The following fields may be set for files: 
ioFlAttrib 
$01 - to lock file ($02 access bit clear) 
$02 - if file may not be deleted ($40 access bit clear) 
$20 - if file may not be renamed ($80 access bit clear) 
$40 - to force MacUnary format 
all other bits ignored 
NOTE: The Macintosh does not support recognition of bits $02 
and $20 as described above—they are included to reflect 
the access bits in the ProDOS directory entry more accurately. 
NOTE: If the MacUnary bit is set for a file that is not in 
MacUnary format, it forces the file to be MacUnary. If 
the MacUnary bit is cleared for a file that is in MacUnary 
format, this call reverts it to normal format # the file 
type and creator are legal and the resource fork is empty; 
otherwise this call fails. 
ioFIFndrInfo 
fdtype - reflects ProDOS file type and auxiliary file type 
TEXT - TXT ($04) with zero aux file type 
'BINA' - typeless ($00) with zero aux file type 
"ZSYS' - SYS with $2000 aux file type 
all nulls - typeless ($00) with zero aux file type 
byte 1 = 'p' (Ascii $70): 
byte 2: file type - one byte value, ProDOS file type 
byte 3: aux file type - two byte value, ProDOS 
auxiliary file type 
all other file types force file to be MacUnary format 
fdcreator - 'pdos' or all nulls (same as 'pdos?) 
anything else forces file to be MacUnary format 
fdFlags - reflects the "Read-allowed" access bit 
$4000 - if file is invisible ($01 access bit) 
all other bits ignored 
ioFlCrDat - creation date 
ioFIMdDat - modification date 
ioF1BkDat - if less than the modification date, sets Changed access 
bit, otherwise ignored 
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The next sequence illustrates some of the more advanced functions of InterFile, even though the 


user never actually copies a file across. 


User 
e Start InterFile 
* Insert Disk 


* Select Eligible File command from File 


e Deselect a conversion 


e Select files 
* Deselect Eligible File command 
* Select Rename Dest. Files command 


e Rename destination files, click Done 


e Eject disk that has the program on it 
e Select About InterFile command 


e Exit InterFile 


Message sent to conversion 
cvt_Init—initialize conversion for all menus 


cvt Appear—menu in which conversion resides 
appears in the menu bar 
cvt_Get—get the menu's appearance 


cvt_Recognize—sent to see which files are eligible and 
should therefore remain undimmed 


cvt_Inactive—sent to the appropriate conversion 

cvt_Recognize—sent to those conversions which are 
listed below the one that was just deactivated; this 
is so that we can see if a particular file previously 
eligible is still eligible. 


nothing (unless file selection involves showing a new 
directory, in which case files in that directory will 
be checked for recognition) 

nothing 


cvt_NewName—sent to get suggested destination file 
names for the selected files 


nothing 


cvt. Load—sent to notify conversions to load any 
miscellaneous resources before the disk goes awav 


cvt. About—either displays About box or returns 
resource ID of TEXT resource with information. 


cvt. Finis 


These final sequences show special cases of a conversion saying it can convert the file (that is, 
"recognizing" it) when in fact it turns out it can't. There are two versions: 
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The function for calling a foreign file system is as follows: 


Function CallFS(msg : integer; fsdata : ptr; pb : ptr: 
async : boolean; fsroutine : handle) : OSErr; 


The first parameter, Msg, identifies the desired operation. It has a value from 0 to 73, depending 
on the desired operation. A list of the legal values for Msg is in Table 3. 


The first 31 operations (FFGetVInfo through FFGetWDInfo) have corresponding functions in the 
Macintosh OS calls (PBHGetVolInfo through PBGetWDInfo). The FFOKFName operation 
returns an error if the file name passed to it in the IONamePt field of the parameter block (pointed 
at by PB) is not a legal Macintosh file name. The FFMakeFName operation is passed a pointer to a 
string (in the IONamePtr field) that gets converted into a legal Macintosh file name. The FFUserl 
through FFUser10 operations are defined individually by the different file systems. 


The FSData parameter contains a pointer to the appropriate global data for this file system; you 
should pass it the value given you in the conversion parameter block—-either cvtFrData or 
cvtToData. 


The PB parameter usually contains a pointer to a parameter block of one flavor or another, 
depending upon the call being made (it can point to a ParamBlockRec, an HParamBlockRec, a 
CInfoPBRec, a CMovePBRec, or a WDPBRec). 


Note: Any call that has two variants in the Macintosh world —PBxxxxx and PBHxxxxx—has 
only one instance in the InterFile world; you should assume the HFS version of the operation and 
therefore pass a pointer to an HParamBlockRec (and not to a ParamBlockRec, which will be too 
short). 


FFGetVInfo = 1; FFGetFinfo = 26; 
FFSetVInfo = 2; FFSetFInfo - 27; 
FFFlushVol = 5; FFSetFLock = 28; 
FFOpen = 9; FFRStF Lock = 29; 
FFOpenRF = 10; FFSetFVers - 30; 
FFLockRange = 11; FFRename - 3]; 
FFUnlockRange = 12; FFGetCatInfo = 32; 
FFRead = 13; FFSetCatInfo = 33; 
FFWrite = 14; FFOpenWD - 35; 
FFGetFPos - 15; FFCloseWD - 36; 
FFSetFPos = 16; FFGetWDInfo  * 37; 
FFGetEOF - 17; FFOKFName = 41; 
FFSet EOF = 18; FFMakeFName - 47; 
FFAllocate = 19; FFUserl - 64; 
FFAllocContig = 20; FFUserZ2 - 65; 
FFFlushFile - 21; FFUser3 = 66; 
FFClose = 22; FFUser4 = 67; 
FFCreate = 23; FFUser5 - 68; 
FFDirCreate - 24; FFUser6 = 69; 
FFDelete - 25; FFUser?7 = 70; 

FFUser8 = 71; 

FFUser9 x 72; 

FFUser10 = 73; 


Table 3. Values for Msg parameter in CallFS 
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FFSetVInfo | ^ 
The following are ignored: 
ioVCIpSiz 
ioV SeqNum = 
io VFndrinfo 


The following fields may be set: 
ioV Atrb - volume attributes (reflects access bits in ProDOS) 
$8000 - if locked by software ($02 access bit clear) 
$0800 - if may not be read ($01 access bit clear) 
$0400 - if may not be renamed ($40 access bit clear) 
$0200 - if may not be reformatted ($80 access bit clear) 
all other bits ignored 
NOTE: The Macintosh does not support recognition of bits $0800, 
$0400, and $0200 as described above-—they are included to 
reflect the access bits in the ProDOS directory entry more 
accurately. 
ioVCrDate - creation date 
ioVLsMod - if greater than ioVBkUp, sets Changed bit in access bits 
io VBkUp - ignored if different than creation date 


FFOpenRF 
Will open resource fork on all files. If the program subsequently 
issues a write call (FF Write) to this fork, it forces the file 
to be converted to the MacUnary format. 


FF Write 
For data forks, works the same as on the Macintosh. For resource forks, 


if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. 


FFSetEOF 
For data forks, works the same as on the Macintosh. For resource forks, 


if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. 


FFAllocate 
For data forks, works the same as on the Macintosh. For resource forks, 


if this is the first write to the fork, then this call forces the file 
to be in MacUnary format. | 


FFAllocContig 
For data forks, works the same as on the Macintosh. For resource forks, 
if this is the first write to the fork, then this call forces the file 


to be in MacUnary format. 


FFCreate 
Creates a typeless file (ProDOS file type $00). To set the type, you 
must issue a FFSetFInfo or FFSetCatInfo call. 
If the name of the file created does not conform to ProDOS conventions, 
the FFCreate call will fail for "Bad file name" error. 
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FFSetFInfo 
The following fields are ignored: 
ioFiIFndrInfo 
fdLocation 
fdFidr 


The following fields may be set: 


ioFIFndrInfo 
fdtype - reflects ProDOS file type and auxiliary file type 


"TEXT - TXT ($04) with zero aux file type 
'BINA' - typeless ($00) with zero aux file type 
"ZSYS' - SYS with $2000 aux file type 
all nulls - typeless ($00) with zero aux file type 
byte 1 = 'p' (Ascii $70): 
byte 2: file type - one byte value, ProDOS file type 
byte 3: aux file type - two byte value, ProDOS 
auxiliary file type 
all other file types force file to be MacUnary format 
fdcreator - 'pdos' or all nulls (same as ‘pdos’) 
anything else forces file to be MacUnary format 
fdFlags - reflects the "Read-allowed" access bit 
$4000 - if file is invisible ($01 access bit) 
all other bits ignored 
ioFlCrDat - creation date 
ioFIMdDat - modification date 


FFSetFVers 
Returns NoErr, but does not affect file. 


FFRename 


If the new name does not follow the ProDOS convention, this call 


will fail for bad file (or directory, or volume) name. 
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The following fields return zero for directories: 
ioFRefNum 
ioDrUsrWds 
ioDrFndrinfo 


The following fields return values for directories: 
ioNamePrr - if directory specified by ioFDirindex 
ioF Attrib - dir attributes—reflects some of ProDOS access bits 
$01 - if dir locked ($02 access bit clear) 
$02 - if may not be deleted ($80 access bit clear) 
$04 - if may not be renamed ($40 access bit clear) 
$08 - if may not be read ($01 access bit clear) 
$10 - always set (indicates directory) 
$20 - if directory allows subdirectory (usually set) 
all other bits clear 
NOTE: The Macintosh does not support recognition of bits $02, 
$04, $08, and $20 as described above—they are included 
to reflect the access bits in the ProDOS directory entry 
more accurately. 
ioDrDirID - directory ID (root is indicated by 2) 
ioDrNmFIs - number of files and directories in this directory 
ioDriCrDat - creation date 
ioDrMdDat - modification date, same as creation, or creation + 1 if 
Changed access bit is set 
ioDrBkDat - backup date, same as creation date 
ioDrParID - ID of parent of specified file (2 indicates root, 0 
indicates no parent, that is, we're already talking about the 
root and we can't go any higher) 


The PBGetCatInfo call is perhaps the strangest routine in the ROM. It is also one of the most powerful, so you 
have to put up with it. In case you have difficulty understanding how it works, here is a short summary: 


ioFDirIndex = n (> 0) 
INPUT 
ioNamePtr - ignored 
ioDirID - if 0, use ioVRefNum for volume and directory, else use ioDirID for directory 
OUTPUT 
ioNamePtr^ - returns name of nth file or directory 
ioDirID - returns file number (ioFINum) or directory number (ioDrDirID) 
ioFIParID - returns directory number of parent of nth file or directory 


ioFDirIndex = 0 
INPUT 
ioNamePtr^ - contains name of file in question (error if ioNamePtr = NIL) 
ioDirID - if 0, use ioVRefNum for volume and directory, else use ioDirID for directory 
OUTPUT 
ioNamePtr^ - unchanged 
ioDirID - returns file number (ioFINum) or directory number (ioDrDirID) 
ioFIParID - returns directory number of parent of file or directory in question 
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The following fields are ignored for directories: 
1oDrUsrWds 
ioDrFndrInfo 


The following fields return values for directories: 
ioNamePr - if directory specified by ioFDirindex 
ioFlAttrib - dir attributes—reflects some of ProDOS access bits 
$01 - if dir locked ($02 access bit clear) 
$02 - if may not be deleted ($80 access bit clear) 
$04 - if may not be renamed ($40 access bit clear) 
$08 - if may not be read ($01 access bit clear) 
all other bits ignored 
NOTE: The Macintosh does not support recognition of bits $02, 
$04, and $08 as described above—they are included 
to reflect the access bits in the ProDOS directory entry 
more accurately. 
ioDrCrDat - creation date 
ioDrMdDat - modification date, if greater than backup date, set the 
Changed access bit, otherwise ignored 
ioDrBkDat - backup date, used to set Changed access bit, otherwise 
ignored 


The following calls behave as they do on the Macintosh with no difference: 
FFFlushVol 
FFOpen 
FFLockRange 
FFUnLockRange 
FFRead 
FFWrite 
FFGetFPos 
FFSetFPos 
FFGetEOF 
FFFlushFile 
FFClose 
FFDelete 
FFSetFLock 
FFRstFLock 


The following calls are not supported for ProDOS: 
FFOpenWD 
FFCloseWD 
FFGetWDiInfo 


The MacUnary format (see Part 5) is fully supported by the ProDOS foreign file system with an 
internal clump size of 512 bytes for the data and resource forks, and a header size of 512 bytes. 
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